API reference (2.0)
Complete reference documentation for the Cryptr API. Includes code snippets and examples.
The Organizations allows you to manage your business-to-business (B2B) customers, and segments strictly that end-users access their applications. Each end-user is stored in a distinct directory for a dedicated customer (Organization), and the end-user experience is customized in your colors with a white label user interface. An (Organization) represents a business customer or partner in your Cryptr service.
- An (Organization) represents a business customer or partner in your Cryptr service.
The Organization type
Each new organization gets a domain generated from its name. A domain is impossible to update because it's the identifier of the organization.
__type__ | string The |
allowed_email_domains | Array of strings or null Current allowed email domain(s) for organization users to log in. |
color | string The color of your organization’s logo in your Cryptr Dashboard. |
domain | slug Immutable identifier of the organization in a 'slug format': domain is a string value in lowercase with underscores, generated from the name. |
Array of objects (Environment) An array containing a sandbox object and a default object (which represents the two environments of an organization) with their status to indicate if they’re active or not. | |
icon_logo_url | string The URL of your organization’s logo in icon format. |
inline_logo_url | string The URL of your organization’s logo in inline format |
inserted_at | string <date-time> Date time of the insertion |
locale | string Your organization’s preferred locale |
name | string The name of your organization will be sluggified and stored at the |
object (Status) This | |
timezone | string Your organization’s preferred timezone |
updated_at | string <date-time> Update timestamp |
{- "__type__": "Organization",
- "allowed_email_domains": [
- "weeklymotion.com"
], - "color": "red-500",
- "domain": "weeklymotion",
- "environments": [
- {
- "name": "production",
- "status": "down"
}, - {
- "name": "sandbox",
- "status": "down"
}
], - "inserted_at": "2023-05-10T06:16:35",
- "locale": "en-US",
- "name": "Weeklymotion",
- "status": {
- "errors": [ ],
- "estimated_time_to_complete_in_seconds": null,
- "progress_in_percentage": null,
- "state": "pending"
}, - "timezone": "Coordinated Universal Time (UTC)",
- "updated_at": "2023-05-10T06:16:35"
}
Create an Organization
Creates a new Organization type with a name.
RETURNS
Returns an Organization if the creation succeeded. Returns an error if the create parameters are invalid (e.g., specifying an invalid code or an invalid source).
query Parameters
name required | string Example: name=Weeklymotion The name of your organization will be sluggified and stored at the |
allowed_email_domains[] | Array of arrays Example: allowed_email_domains[]=weeklymotion.com List of email domains from the professional emails of the users |
Responses
Request samples
- cURL
- Java
- Node JS
- Kotlin
- PHP
- Python
- Ruby
curl -X POST ${cryptr_service_url}/api/v2/organizations \ -H "Authorization: Bearer your-access-token-from-client-id-and-secret" \ -d name="Communitiz App" \ -d allowed_email_domains[]="communitz-app"
Response samples
- 201
- 422
{- "__type__": "Organization",
- "allowed_email_domains": [
- "weeklymotion.com"
], - "color": "red-500",
- "domain": "weeklymotion",
- "environments": [
- {
- "name": "production",
- "status": "down"
}, - {
- "name": "sandbox",
- "status": "down"
}
], - "inserted_at": "2023-05-04T07:16:56",
- "locale": "en-US",
- "name": "Weeklymotion",
- "status": {
- "errors": [ ],
- "estimated_time_to_complete_in_seconds": null,
- "progress_in_percentage": null,
- "state": "pending"
}, - "timezone": "Coordinated Universal Time (UTC)",
- "updated_at": "2023-05-04T07:16:56"
}
Delete an Organization
path Parameters
org_domain required | string Example: weeklymotion The domain is a string value in lowercase with dashes, generated from the organization’s name. |
Responses
Request samples
- cURL
curl -X DELETE '${cryptr_service_url}/api/v2/organizations/${org_domain}'
Response samples
- 200
- 401
{- "deleted": true,
- "resource": {
- "__type__": "Organization",
- "allowed_email_domains": [
- "weeklymotion.com"
], - "color": "red-500",
- "domain": "weeklymotion",
- "environments": [
- {
- "name": "production",
- "status": "down"
}, - {
- "name": "sandbox",
- "status": "down"
}
], - "inserted_at": "2023-05-04T07:16:56",
- "locale": "en-US",
- "name": "Weeklymotion",
- "status": {
- "errors": [ ],
- "estimated_time_to_complete_in_seconds": null,
- "progress_in_percentage": null,
- "state": "pending"
}, - "timezone": "Coordinated Universal Time (UTC)",
- "updated_at": "2023-05-04T07:16:56"
}
}
List all Organizations
Returns a list of your Organizations. The Organizations are returned sorted by creation date, with the most recent customers appearing first.
RETURNS
A dictionary with a data
property that contains an array of up to the limit of Organizations. Each entry in the array represents a separate Organization type. If no Organizations are available, the resulting array will be empty. This request should never return an error.
query Parameters
page | integer Example: page=1 Precise the page of your listing. |
per_page | integer Example: per_page=8 Precise the size of the pages of the pagination of the list. |
q[environments_status_in][] | string Example: q[environments_status_in][]=up Filter organizations by functional or non-functional environments. |
Responses
Request samples
- cURL
curl '${cryptr_service_url}/api/v2/organizations' \ -d "page=${page}" \ -d "per_page=${per_page}" \ -d "q[environments_status_in][]=up"
Response samples
- 200
{- "__type__": "List",
- "data": [
- {
- "__type__": "Organization",
- "allowed_email_domains": [ ],
- "color": "red-500",
- "domain": "actalab-corp-prod",
- "environments": [
- {
- "name": "production",
- "status": "up"
}, - {
- "name": "sandbox",
- "status": "up"
}
], - "inserted_at": "2023-06-08T08:13:54",
- "locale": "en-US",
- "name": "Actalab Corp Prod",
- "status": {
- "errors": [ ],
- "estimated_time_to_complete_in_seconds": null,
- "progress_in_percentage": null,
- "state": "pending"
}, - "timezone": "Coordinated Universal Time (UTC)",
- "updated_at": "2023-06-08T08:14:12"
}, - {
- "__type__": "Organization",
- "allowed_email_domains": [ ],
- "color": "red-500",
- "domain": "actalab-corp-prod",
- "environments": [
- {
- "name": "production",
- "status": "up"
}, - {
- "name": "sandbox",
- "status": "up"
}
], - "inserted_at": "2023-06-08T08:13:54",
- "locale": "en-US",
- "name": "Actalab Corp Prod",
- "status": {
- "errors": [ ],
- "estimated_time_to_complete_in_seconds": null,
- "progress_in_percentage": null,
- "state": "pending"
}, - "timezone": "Coordinated Universal Time (UTC)",
- "updated_at": "2023-06-08T08:14:12"
}, - {
- "__type__": "Organization",
- "allowed_email_domains": [ ],
- "color": "red-500",
- "domain": "tutux-corp-sandbox",
- "environments": [
- {
- "name": "production",
- "status": "down"
}, - {
- "name": "sandbox",
- "status": "up"
}
], - "inserted_at": "2023-06-08T08:08:53",
- "locale": "en-US",
- "name": "Tutux Corp Sandbox",
- "status": {
- "errors": [ ],
- "estimated_time_to_complete_in_seconds": null,
- "progress_in_percentage": null,
- "state": "pending"
}, - "timezone": "Coordinated Universal Time (UTC)",
- "updated_at": "2023-06-08T08:09:10"
}, - {
- "__type__": "Organization",
- "allowed_email_domains": [ ],
- "color": "red-500",
- "domain": "tutux-corp-sandbox",
- "environments": [
- {
- "name": "production",
- "status": "down"
}, - {
- "name": "sandbox",
- "status": "up"
}
], - "inserted_at": "2023-06-08T08:08:53",
- "locale": "en-US",
- "name": "Tutux Corp Sandbox",
- "status": {
- "errors": [ ],
- "estimated_time_to_complete_in_seconds": null,
- "progress_in_percentage": null,
- "state": "pending"
}, - "timezone": "Coordinated Universal Time (UTC)",
- "updated_at": "2023-06-08T08:09:10"
}
], - "pagination": {
- "current_page": 1,
- "current_pages": [
- 1
], - "next_page": null,
- "per_page": 8,
- "prev_page": null,
- "total_pages": 1
}, - "total": 4
}
Retrieve an Organization
Fetch an Organization using its domain. The domain is generated from its name and serves as a unique and immutable value in your Cryptr service.
RETURNS
Returns the Organization for a valid identifier. If the identifier corresponds to a deleted Organization, a subset of its information is returned, including a 'deleted' property set to true.
path Parameters
org_domain required | string Example: weeklymotion The domain is a string value in lowercase with dashes, generated from the organization’s name. |
Responses
Request samples
- cURL
curl '${cryptr_service_url}/api/v2/organizations/${org_domain}'
Response samples
- 200
- 401
{- "__type__": "Organization",
- "allowed_email_domains": [
- "weeklymotion.com"
], - "color": "red-500",
- "domain": "weeklymotion",
- "environments": [
- {
- "name": "production",
- "status": "down"
}, - {
- "name": "sandbox",
- "status": "down"
}
], - "inserted_at": "2023-05-04T07:16:56",
- "locale": "en-US",
- "name": "Weeklymotion",
- "status": {
- "errors": [ ],
- "estimated_time_to_complete_in_seconds": null,
- "progress_in_percentage": null,
- "state": "pending"
}, - "timezone": "Coordinated Universal Time (UTC)",
- "updated_at": "2023-05-04T07:16:56"
}
Update an Organization
You can’t update the domain of an Organization. If you need to, you have to create a new one.
RETURNS
Returns the Organization if the update succeeded. Returns an error if the update parameters are invalid (e.g., specifying an invalid code or an invalid source).
path Parameters
org_domain required | string Example: weeklymotion The domain is a string value in lowercase with dashes, generated from the organization’s name. |
query Parameters
name | string Example: name=Weeklymotion The name of your organization (the domain is set at creation and remains unchanged, but the name can be updated). |
allowed_email_domains[] | Array of arrays Example: allowed_email_domains[]=weeklymotion.com List of email domains from the professional emails of the users |
Responses
Request samples
- cURL
curl -X PUT '${cryptr_service_url}/api/v2/organizations/${org_domain}'
Response samples
- 200
- 401
- 422
{- "__type__": "Organization",
- "allowed_email_domains": [
- "weeklymotion.com"
], - "color": "red-500",
- "domain": "weeklymotion",
- "environments": [
- {
- "name": "production",
- "status": "down"
}, - {
- "name": "sandbox",
- "status": "down"
}
], - "inserted_at": "2023-05-04T07:16:56",
- "locale": "en-US",
- "name": "Weeklymotion",
- "status": {
- "errors": [ ],
- "estimated_time_to_complete_in_seconds": null,
- "progress_in_percentage": null,
- "state": "pending"
}, - "timezone": "Coordinated Universal Time (UTC)",
- "updated_at": "2023-05-04T07:16:56"
}
Cryptr stores user profiles for your application in a dedicated hosted cloud database for a specific Organization. User profile information can come from your users directly. The sources are magic link signup, SSO (via SAML) logins, or Active Directory.
- A (User) represents an end user of your customer or partner in your Cryptr service.
Your Cryptr subscription plan could limit the number of users. See our pricing for more details.
The User’s Organization domain
Each end user is stored in a distinct directory specific to a dedicated customer (Organization). You can determine the domain of the user’s Organization from this user’s domain’s attribute.
The User type
Each new user gets a unique id (identifier) generated and which is impossible to update.
__domain__ | string The domain is a string value in lowercase with dashes, generated from the organization’s name. |
__environment__ | string The environment in which the user is stored, either sandbox (for the test environment) or production. |
__type__ | string Data type |
active | boolean Boolean that indicates if the user is considered active or not. |
object (Address) User’s postal address. The value of the address member is of type | |
string <email> | |
email_verified | boolean Boolean that indicates if the email has been verified. |
id | uuid The immutable identifier. |
Array of objects (Identity) User's identities | |
inserted_at | string <date-time> Insertion datetime. |
metadata | Array of arrays User’s metadata. See Token > Create a User Metakey |
phone_number | string User’s telephone number in E.164 format. |
phone_number_verified | boolean Boolean that indicates whether the phone number has been verified. |
Array of objects (PhoneNumber) User's phone numbers | |
object (Profile) The OpenID Connect profile specification defines a set of standard Claims. They can be requested to be returned either in the UserInfo Response or in the ID Token. | |
updated_at | string <date-time> Update timestamp |
{- "__domain__": "loirama",
- "__environment__": "sandbox",
- "__type__": "User",
- "active": true,
- "address": {
- "country": "FR",
- "formatted": "165 avenue de Bretagne\n59000 Lille, France",
- "locality": "Lille",
- "postal_code": "59000",
- "region": "Nord",
- "street_address": "165 avenue de Bretagne"
}, - "email": "lyla@loirama.co",
- "email_verified": false,
- "id": "d6a46443-c7bc-4259-aa5d-ce51cc548b57",
- "identities": [ ],
- "inserted_at": "2023-05-10T13:50:35",
- "meta_data": [ ],
- "phone_number": "+33 1 23 45 67 89",
- "phone_number_verified": false,
- "phone_numbers": [ ],
- "profile": {
- "birthdate": "1992-03-10",
- "family_name": "Bloggs",
- "gender": "female",
- "given_name": "Lyla",
- "locale": "fr",
- "nickname": "lylaB",
- "preferred_username": null,
- "zoneinfo": "France/Lille"
}, - "updated_at": "2023-05-10T13:50:35"
}
The Profile type
birthdate | string User’s birthday represented in ISO 8601:2004 [ISO8601-2004] YYYY-MM-DD format. |
family_name | string The last name is an OpenID Connect profile attribute. |
gender | enum It’s an OpenID Connect profile attribute. |
given_name | string The first name is an OpenID Connect profile attribute. |
locale | enum It’s an OpenID Connect profile attribute. |
nickname | string It’s an OpenID Connect profile attribute. |
picture | url It’s an OpenID Connect profile attribute. |
preferred_username | string or null It’s an OpenID Connect profile attribute. |
website | url It’s an OpenID Connect profile attribute. |
zoneinfo | enum It’s an OpenID Connect profile attribute. |
{- "birthdate": "1992-03-10",
- "family_name": "Bloggs",
- "gender": "female",
- "given_name": "Lyla",
- "locale": "fr",
- "nickname": "lylaB",
- "preferred_username": null,
- "zoneinfo": "France/Lille"
}
The Address type
country | string Country name component. |
formatted | string The full mailing address is formatted to display or use on a mailing label. This field MAY contain multiple lines, separated by newlines. Newlines can be represented either as a carriage return/line feed pair ("\r\n") or as a single line feed character ("\n"). |
locality | string City or locality component. |
postal_code | string Zip code or postal code component of the User. |
region | string State, province, prefecture, or region component of the User. |
street_address | string The complete address includes house number, street name, PO box, and extended street address information on multiple lines. This field may contain multiple lines, separated by newlines. Newlines can be represented either as a carriage return/line feed pair ("\r\n") or as a single line feed character ("\n"). |
{- "country": "FR",
- "formatted": "165 avenue de Bretagne\n59000 Lille, France",
- "locality": "Lille",
- "postal_code": "59000",
- "region": "Nord",
- "street_address": "165 avenue de Bretagne"
}
Add User Metadata
You can add a metadata key, which you have previously created using the Metakey request, by assigning a specific value to a user.
RETURNS
This request returns the user you selected if the creation is successful. If the metadata key is not declared in your account, an error will be returned.
path Parameters
org_domain required | string Example: loirama The domain is a string value in lowercase with dashes, generated from the organization’s name. |
user_id required | string Example: 4061e243-b452-4fe4-b9f7-7cb8ec39ce95 The ID of the User for which you want to add Metadata |
query Parameters
key required | string Example: key=uid The key of the value you want to add to your User. |
value required | string Example: value=2fa42937 The value you want to add to your User, stored in a custom key. |
Responses
Request samples
- cURL
curl -X PUT '${cryptr_service_url}/api/v2/org/:org_domain/users/:user_id/add-metadata' \ -d key='uid' \ -d value='2fa42937'
Response samples
- 200
- 401
- 404
{- "__domain__": "loirama",
- "__environment__": "sandbox",
- "__type__": "User",
- "active": true,
- "address": {
- "country": "FR",
- "formatted": "165 avenue de Bretagne\n59000 Lille, France",
- "locality": "Lille",
- "postal_code": "59000",
- "region": "Nord",
- "street_address": "165 avenue de Bretagne"
}, - "email": "lyla@loirama.co",
- "email_verified": false,
- "id": "d6a46443-c7bc-4259-aa5d-ce51cc548b57",
- "identities": [ ],
- "inserted_at": "2023-05-10T13:50:35",
- "meta_data": [ ],
- "phone_number": "+33 1 23 45 67 89",
- "phone_number_verified": false,
- "phone_numbers": [ ],
- "profile": {
- "birthdate": "1992-03-10",
- "family_name": "Bloggs",
- "gender": "female",
- "given_name": "Lyla",
- "locale": "fr",
- "nickname": "lylaB",
- "preferred_username": null,
- "zoneinfo": "France/Lille"
}, - "updated_at": "2023-05-10T13:50:35"
}
Create a User
Creates a new User in an Organization.
RETURNS
Returns a User attached to an Organization if the creation succeeded. Returns an error if the creation parameters are invalid (e.g., specifying an invalid code or an invalid source).
path Parameters
org_domain required | string Example: loirama The domain is a string value in lowercase with dashes, generated from the organization’s name. |
query Parameters
email required | string Example: email=lyla@loirama.co Email is a required field as it is part of the security for the created end-user account. |
phone_number | |
object (Profile) Example: birthdate=1992-03-10&family_name=Bloggs&gender=female&given_name=Lyla&locale=fr&nickname=lylaB&picture=http://www.example.com/avatar.jpeg&website=http://www.example.com&zoneinfo=France/Lille The OpenID Connect profile specification defines a set of standard Claims. They can be requested to be returned either in the UserInfo Response or in the ID Token. |
Responses
Request samples
- cURL
curl -X POST '${cryptr_service_url}/api/v2/org/${org_domain}/users' --form 'profile[address][country]="FR"' --form 'profile[address][formatted]="165 avenue de Bretagne 59000 Lille, France"' --form 'profile[address][locality]="Lille"' --form 'profile[address][postal_code]="59000"' --form 'profile[address][region]="Nord"' --form 'profile[address][street_address]="165 avenue de Bretagne"' --form 'profile[email]="lyla@loirama.co"' --form 'profile[birthdate]="1992-03-10"' --form 'profile[phone_number]="+33123456789"' --form 'profile[given_name]="Lyla"' --form 'profile[family_name]="Bloggs"' --form 'profile[nickname]="lylaB"' --form 'profile[picture]="http://www.example.com/avatar.jpeg"' --form 'profile[website]="http://www.example.com"' --form 'profile[gender]="female"' --form 'profile[zoneinfo]="France/Lille"' --form 'profile[locale]="fr"'
Response samples
- 201
- 422
{- "__domain__": "loirama",
- "__environment__": "sandbox",
- "__type__": "User",
- "active": true,
- "address": {
- "country": "FR",
- "formatted": "165 avenue de Bretagne\n59000 Lille, France",
- "locality": "Lille",
- "postal_code": "59000",
- "region": "Nord",
- "street_address": "165 avenue de Bretagne"
}, - "email": "lyla@loirama.co",
- "email_verified": false,
- "id": "d6a46443-c7bc-4259-aa5d-ce51cc548b57",
- "identities": [ ],
- "inserted_at": "2023-05-10T13:50:35",
- "meta_data": [ ],
- "phone_number": "+33 1 23 45 67 89",
- "phone_number_verified": false,
- "phone_numbers": [ ],
- "profile": {
- "birthdate": "1992-03-10",
- "family_name": "Bloggs",
- "gender": "female",
- "given_name": "Lyla",
- "locale": "fr",
- "nickname": "lylaB",
- "preferred_username": null,
- "zoneinfo": "France/Lille"
}, - "updated_at": "2023-05-10T13:50:35"
}
Delete a User By ID
path Parameters
org_domain required | string Example: b-oreal The domain is a string value in lowercase with dashes, generated from the organization’s name. |
user_id required | uuid Example: 796ffbba-1698-4b64-b667-5e5006fb52d2 The immutable identifier. |
Responses
Request samples
- cURL
curl -X DELETE '${cryptr_service_url}/api/v2/org/${org_domain}/users/${user_id}'
Response samples
- 200
- 401
{- "deleted": true,
- "resource": {
- "__domain__": "b-oreal",
- "__environment__": "sandbox",
- "__type__": "User",
- "active": true,
- "address": {
- "country": "FR",
- "formatted": "165 avenue de Bretagne\n59000 Lille, France",
- "locality": "Lille",
- "postal_code": "59000",
- "region": "Nord",
- "street_address": "165 avenue de Bretagne"
}, - "email": "karim@b-oreal.co",
- "email_verified": false,
- "id": "796ffbba-1698-4b64-b667-5e5006fb52d2",
- "identities": [ ],
- "inserted_at": "2023-05-04T13:23:32",
- "meta_data": [ ],
- "phone_number": null,
- "phone_number_verified": false,
- "phone_numbers": [ ],
- "profile": {
- "birthdate": "1992-03-10",
- "family_name": "Guerra",
- "gender": "male",
- "given_name": "Karim",
- "locale": "fr",
- "nickname": "kGuerra",
- "preferred_username": null,
- "zoneinfo": "France/Lille"
}, - "updated_at": "2023-05-04T13:23:32"
}
}
List all Users
Returns a list of your users, sorted by creation date, with the most recent users appearing first.
RETURNS
A dictionary with a data property that contains an array of up to limit users. Each entry in the array represents a separate user type. If no users are available, the resulting array will be empty. This request should never return an error.
path Parameters
org_domain required | string Example: loirama The domain is a string value in lowercase with dashes, generated from the organization’s name. |
query Parameters
page | integer Example: page=1 Precise the page of your listing. |
per_page | integer Example: per_page=8 Precise the size of the pages of the pagination of the list. |
Responses
Request samples
- cURL
- Java
- Node JS
- Kotlin
- PHP
- Python
- Ruby
curl "${cryptr_service_url}/api/v2/org/${org_domain}/users" \ -d page=${page} -d per_page=${per_page}
Response samples
- 200
- 401
{- "__type__": "List",
- "data": [
- {
- "__domain__": "b-oreal",
- "__environment__": "sandbox",
- "__type__": "User",
- "active": true,
- "address": {
- "country": "FR",
- "formatted": "165 avenue de Bretagne\n59000 Lille, France",
- "locality": "Lille",
- "postal_code": "59000",
- "region": "Nord",
- "street_address": "165 avenue de Bretagne"
}, - "email": "audrey@b-oreal.co",
- "email_verified": false,
- "id": "9aaf8fb9-89b8-488d-a5bc-dd61b7e63f2e",
- "identities": [ ],
- "inserted_at": "2023-05-04T13:24:49",
- "meta_data": [ ],
- "phone_number": null,
- "phone_number_verified": false,
- "phone_numbers": [ ],
- "profile": {
- "birthdate": "1992-03-10",
- "family_name": "Gallagher",
- "gender": "female",
- "given_name": "Audrey",
- "locale": "fr",
- "nickname": "aGallagher",
- "preferred_username": null,
- "zoneinfo": "France/Lille"
}, - "updated_at": "2023-05-04T13:24:49"
}, - {
- "__domain__": "b-oreal",
- "__environment__": "sandbox",
- "__type__": "User",
- "active": true,
- "address": {
- "country": "FR",
- "formatted": "165 avenue de Bretagne\n59000 Lille, France",
- "locality": "Lille",
- "postal_code": "59000",
- "region": "Nord",
- "street_address": "165 avenue de Bretagne"
}, - "email": "karim@b-oreal.co",
- "email_verified": false,
- "id": "796ffbba-1698-4b64-b667-5e5006fb52d2",
- "identities": [ ],
- "inserted_at": "2023-05-04T13:23:32",
- "meta_data": [ ],
- "phone_number": null,
- "phone_number_verified": false,
- "phone_numbers": [ ],
- "profile": {
- "birthdate": "1992-03-10",
- "family_name": "Guerra",
- "gender": "male",
- "given_name": "Karim",
- "locale": "fr",
- "nickname": "kGuerra",
- "preferred_username": null,
- "zoneinfo": "France/Lille"
}, - "updated_at": "2023-05-04T13:23:32"
}
], - "pagination": {
- "current_page": 1,
- "current_pages": [
- 1,
- 2
], - "next_page": 2,
- "per_page": 2,
- "prev_page": null,
- "total_pages": 2
}, - "total": 3
}
Remove User Metadata
This request allows you to remove a metadata key assigned to a user.
RETURNS
This request returns the user you selected if the removal is successful. If the metadata key is not declared in your account, an error will be returned.
path Parameters
org_domain required | string Example: loirama The domain is a string value in lowercase with dashes, generated from the organization’s name. |
user_id required | string Example: 4061e243-b452-4fe4-b9f7-7cb8ec39ce95 The ID of the User for which you want to add Metadata |
query Parameters
key required | string Example: key=uid The key of the value you want to remove from your User. |
Responses
Request samples
- cURL
curl -X PUT '${cryptr_service_url}/api/v2/org/:org_domain/users/:user_id/remove-metadata' \ -d key='uid'
Response samples
- 200
- 401
- 404
{- "__domain__": "loirama",
- "__environment__": "sandbox",
- "__type__": "User",
- "address": {
- "country": "FR",
- "formatted": "165 avenue de Bretagne\n59000 Lille, France",
- "locality": "Lille",
- "postal_code": "59000",
- "region": "Nord",
- "street_address": "165 avenue de Bretagne"
}, - "email": "lyla@loirama.co",
- "email_verified": false,
- "id": "d6a46443-c7bc-4259-aa5d-ce51cc548b57",
- "inserted_at": "2023-05-10T13:50:35",
- "meta_data": [
- {
- "key": {
- "name": "uid",
- "required": false,
- "type": "string"
}
}
], - "phone_number": "+33 1 23 45 67 89",
- "phone_number_verified": false,
- "profile": {
- "birthdate": "1992-03-10",
- "family_name": "Bloggs",
- "gender": "female",
- "given_name": "Lyla",
- "locale": "fr",
- "nickname": "lylaB",
- "preferred_username": null,
- "zoneinfo": "France/Lille"
}, - "updated_at": "2023-05-10T13:50:35"
}
Retrieve a User By Email or ID
path Parameters
org_domain required | string Example: loirama The domain is a string value in lowercase with dashes, generated from the organization’s name. |
email_or_id required | string Example: janis.joplin@example.com or 86561a93-bee2-4eba-96ff-6769d617eaf8 The user’s email or their UUID (user identifier). |
Responses
Request samples
- cURL
curl '${cryptr_service_url}/api/v2/org/${org_domain}/users/${user_id}'
Response samples
- 200
- 401
{- "__domain__": "loirama",
- "__environment__": "sandbox",
- "__type__": "User",
- "active": true,
- "address": {
- "country": "FR",
- "formatted": "165 avenue de Bretagne\n59000 Lille, France",
- "locality": "Lille",
- "postal_code": "59000",
- "region": "Nord",
- "street_address": "165 avenue de Bretagne"
}, - "email": "lyla@loirama.co",
- "email_verified": false,
- "id": "d6a46443-c7bc-4259-aa5d-ce51cc548b57",
- "identities": [ ],
- "inserted_at": "2023-05-10T13:50:35",
- "meta_data": [ ],
- "phone_number": "+33 1 23 45 67 89",
- "phone_number_verified": false,
- "phone_numbers": [ ],
- "profile": {
- "birthdate": "1992-03-10",
- "family_name": "Bloggs",
- "gender": "female",
- "given_name": "Lyla",
- "locale": "fr",
- "nickname": "lylaB",
- "preferred_username": null,
- "zoneinfo": "France/Lille"
}, - "updated_at": "2023-05-10T13:50:35"
}
Update a User
Update an existing user.
RETURNS
Returns an updated Users from an Organization if the update succeeded. Returns an error if the creation parameters are invalid (e.g., specifying an invalid code or an invalid source).
path Parameters
org_domain required | string Example: loirama The domain is a string value in lowercase with dashes, generated from the organization’s name. |
user_id required | uuid Example: 8724da20-c140-4d01-82d2-bc87079a6f6e The immutable identifier. |
query Parameters
email required | string Example: email=lyla@loirama.co Email is a required field as it is part of the security for the created end-user account. |
birthdate | string Example: birthdate=1992-03-10 User’s birthday represented in ISO 8601:2004 [ISO8601-2004] YYYY-MM-DD format. |
phone_number | |
given_name | |
family_name | |
nickname | |
picture | string <url> Example: picture=http://www.example.com/avatar.jpeg It’s an OpenID Connect profile attribute. |
website | |
gender | string Enum: "male" "female" null Example: gender=female It's an OpenID Connect profile attribute, available options are |
zoneinfo | |
locale |
Responses
Request samples
- cURL
curl -X PUT '${cryptr_service_url}/api/v2/org/${org_domain}/users/${user_id}' --form 'address[country]="FR"' --form 'address[formatted]="165 avenue de Bretagne 59000 Lille, France"' --form 'address[locality]="Lille"' --form 'address[postal_code]="59000"' --form 'address[region]="Nord"' --form 'address[street_address]="165 avenue de Bretagne"' --form 'email="lyla@loirama.co"' --form 'phone_number="+33123456789"' --form 'profile[birthdate]="1992-03-10"' --form 'profile[given_name]="Lyla"' --form 'profile[family_name]="Bloggs"' --form 'profile[nickname]="lylaB"' --form 'profile[picture]="http://www.example.com/avatar.jpeg"' --form 'profile[website]="http://www.example.com"' --form 'profile[gender]="female"' --form 'profile[zoneinfo]="France/Lille"' --form 'profile[locale]="fr"'
Response samples
- 200
- 401
{- "__domain__": "loirama",
- "__environment__": "sandbox",
- "__type__": "User",
- "active": true,
- "address": {
- "country": "FR",
- "formatted": "165 avenue de Bretagne\n59000 Lille, France",
- "locality": "Lille",
- "postal_code": "59000",
- "region": "Nord",
- "street_address": "165 avenue de Bretagne"
}, - "email": "lyla@loirama.co",
- "email_verified": false,
- "id": "d6a46443-c7bc-4259-aa5d-ce51cc548b57",
- "identities": [ ],
- "inserted_at": "2023-05-10T13:50:35",
- "meta_data": [ ],
- "phone_number": "+33 1 23 45 67 89",
- "phone_number_verified": false,
- "phone_numbers": [ ],
- "profile": {
- "birthdate": "1992-03-10",
- "family_name": "Bloggs",
- "gender": "female",
- "given_name": "Lyla",
- "locale": "fr",
- "nickname": "lylaB",
- "preferred_username": null,
- "zoneinfo": "France/Lille"
}, - "updated_at": "2023-05-10T13:50:35"
}
The term Directory Sync in Cryptr refers to the SCIM protocol defined in RFCs 7642, 7643 & 7644. It allows you to synchronize the changes that take place on your user base.
For example, when a user is created, the change is automatically recognized and propagated. SCIM handles creations, deletions, and updates.
The Directory Sync type
The number of directory syncs you can create is limited. You can create only one Directory Sync per organization domain and environment pair. For instance, if your organization domain is misapret and you have a sandbox environment, you can create only one Directory Sync for "misapret/sandbox". However, if you also have a production environment, you can create an additional Directory Sync for the "misapret/production" pair.
__domain__ | string Immutable identifier of the organization in a 'slug format': domain is a string value in lowercase with underscores, generated from the name. |
__environment__ | string The environment in which the user is stored, either sandbox (for the test environment) or production. |
__type__ | string The |
active | boolean Boolean that indicates if a Directory Sync is active |
object (AuthSecretToken) Use the value as a Bearer token for your SCIM implementation in your provider. 💡 This token is available only once upon creation, so be sure to save it. To obtain a new token, you will need to reset your Directory Sync. | |
id | string A unique string that identifies a directory sync. |
inserted_at | string <date-time> Date time of the insertion. |
provider_type | string The name of the provider you use, e.g., |
updated_at | string <date-time> Update timestamp |
{- "__domain__": "barker-inc",
- "__environment__": "sandbox",
- "__type__": "DirectorySync",
- "active": true,
- "auth_secret_token": {
- "hint": "You must save this value. If you lose it you will have to create a new one using the reset endpoint.",
- "provider_key": "OAuth Bearer Token",
- "value": "barker-inc.sandbox.48789cb6-33c3-47fe-bb92-8774cda6d327.CrVrhHZuQfVgGuKkYY7lvBMgsqRU15flunxYOrOhPfGg6IW6wDA2ic41MRMQfge0O_kBXRjLbI4HqFaxBfTdqtbzmGTiFbRZmoIgjjeuqBwROiDprKUQqVAjad3CXjd8"
}, - "id": "32dad740-142e-4af3-ac69-de5f36915d80",
- "inserted_at": "2023-06-15T09:23:55",
- "provider_type": null,
- "updated_at": "2023-06-15T09:23:55"
}
Create a Directory Sync
Creates a new Directory Sync in an Organization. When you create a Directory Sync, you will receive the associated bearer token.
Note: When you create a Directory Sync, the environment of your API key determines where your Directory Sync is stored. For example, a Directory Sync in the sandbox environment is created only if the API key used belongs to the sandbox environment. You cannot create a Directory Sync for the Production environment with an API key meant for another environment; you need an API key dedicated to the Production environment.
path Parameters
org_domain required | string Example: barker-inc The domain is a string value in lowercase with dashes, generated from the organization’s name. |
Responses
Request samples
- cURL
curl -X POST '${cryptr_service_url}/api/v2/org/${org_domain}/directory-sync'
Response samples
- 201
- 401
- 409
{- "__domain__": "barker-inc",
- "__environment__": "sandbox",
- "__type__": "DirectorySync",
- "active": true,
- "auth_secret_token": {
- "hint": "You must save this value. If you lose it you will have to create a new one using the reset endpoint.",
- "provider_key": "OAuth Bearer Token",
- "value": "barker-inc.sandbox.48789cb6-33c3-47fe-bb92-8774cda6d327.CrVrhHZuQfVgGuKkYY7lvBMgsqRU15flunxYOrOhPfGg6IW6wDA2ic41MRMQfge0O_kBXRjLbI4HqFaxBfTdqtbzmGTiFbRZmoIgjjeuqBwROiDprKUQqVAjad3CXjd8"
}, - "id": "32dad740-142e-4af3-ac69-de5f36915d80",
- "inserted_at": "2023-06-15T09:23:55",
- "provider_type": null,
- "updated_at": "2023-06-15T09:23:55"
}
Retrieve a Directory Sync
Fetch a Directory Sync by its organization owner and environment (production, sandbox...).
Note: When you fetch a Directory Sync, the environment of your API key determines where your Directory Sync is stored. For example, your Directory Sync in the sandbox environment is fetched only if this resource is stored in sandbox. You cannot fetch a Directory Sync from the Production environment with this API key; you need an API key dedicated to the Production environment.
RETURNS
Returns the Directory Sync for a valid organization/environment pair. If the Directory Sync has been deleted, a NoResult response is returned.
path Parameters
org_domain required | string Example: misapret The domain is a string value in lowercase with dashes, generated from the organization’s name. |
Responses
Request samples
- cURL
curl -X '${cryptr_service_url}/api/v2/org/${org_domain}/directory-sync'
Response samples
- 200
{- "__domain__": "barker-inc",
- "__environment__": "sandbox",
- "__type__": "DirectorySync",
- "active": true,
- "auth_secret_token": {
- "hint": "This value is only displayed once at creation. If you have lost this value and wish to recover it, please consider using the reset endpoint.",
- "provider_key": "OAuth Access Token",
- "value": "hidden"
}, - "id": "32dad740-142e-4af3-ac69-de5f36915d80",
- "inserted_at": "2023-06-15T09:23:55",
- "provider_type": null,
- "updated_at": "2023-06-15T12:11:17"
}
Update a Directory Sync
Update an existing Directory Sync in an organization. The only update allowed is to change the active field.
RETURNS
Returns the updated Directory Sync for a valid organization/environment pair. If the Directory Sync has been deleted, a NoResult response is returned.
path Parameters
org_domain required | string Example: misapret The domain is a string value in lowercase with dashes, generated from the organization’s name. |
query Parameters
active required | boolean Example: active=true Boolean that indicates if a Directory Sync is active |
Responses
Request samples
- cURL
curl -X PUT '${cryptr_service_url}/api/v2/org/${org_domain}/directory-sync'
Response samples
- 200
- 401
{- "__domain__": "barker-inc",
- "__environment__": "sandbox",
- "__type__": "DirectorySync",
- "active": true,
- "auth_secret_token": {
- "hint": "You must save this value. If you lose it you will have to create a new one using the reset endpoint.",
- "provider_key": "OAuth Bearer Token",
- "value": "barker-inc.sandbox.48789cb6-33c3-47fe-bb92-8774cda6d327.CrVrhHZuQfVgGuKkYY7lvBMgsqRU15flunxYOrOhPfGg6IW6wDA2ic41MRMQfge0O_kBXRjLbI4HqFaxBfTdqtbzmGTiFbRZmoIgjjeuqBwROiDprKUQqVAjad3CXjd8"
}, - "id": "32dad740-142e-4af3-ac69-de5f36915d80",
- "inserted_at": "2023-06-15T09:23:55",
- "provider_type": null,
- "updated_at": "2023-06-15T09:23:55"
}
You can create or update SSO connection preferences for an organization (usually your enterprise customer). This includes setting up, attaching, creating a redirection for end-user login, or interacting with the administrator of the SSO.
Cryptr supports the following SSO provider solutions:
- Azure Active Directory
- ADFS
- Okta
- Ping Federate (Ping Identity)
- Ping One (Ping Identity)
- Auth0
- OneLogin
- Custom SAML
By default, user profile attributes provided by identity providers (the SSO solution of your customers) are not directly editable because they are updated from the identity provider each time the user logs in.
To be able to edit the name
, nickname
, given_name
, family_name
, or picture
root attributes on the normalized user profile, you must configure your connection sync with Cryptr so that user attributes are updated from the identity provider only upon user profile creation.
You can add and edit root attributes individually or via bulk import using the Management API. You'll find these attributes in the final JWT (JSON Web Token) after successful SSO authentication.
- A (User) represents an end user for your customer or partner in your Cryptr service.
Your Cryptr subscription plan may limit the number of users. See our pricing for more details.
__type__ | string The |
active | boolean Default: true Specify if the connection is usable. |
id | string Unique identifier of the Identity Provider used in the SAML protocol. |
inserted_at | string <date-time> Date time of the insertion |
number_users_provisioning_limit | integer The limit of simultaneously possible SSO sessions for the SSO connection. |
object (Organization) Data of the organization | |
provider_type | string The provider type (Okta, Google Workspace, ADFS, etc.) of the SSO connection. |
object (SamlConfig) The SAML configuration includes critical data such as the ACS URL, metadata URL, entity ID, unique logout URL, and identity provider metadata. These elements enable secure authentication and authorization between systems. | |
sp_id | string The service provider (SP) identifier is a unique code that identifies an application or service within an authentication platform. |
updated_at | string <date-time> Update timestamp |
users_access_policy | string Default: "provision_new_users" Defines how users are managed when they log in for the first time via SSO. The options are: |
{- "__type__": "SsoConnection",
- "active": true,
- "id": "barker_inc_S6f5ndf8mZqfoBKoxEotMV",
- "inserted_at": "2023-06-08T13:47:41",
- "number_users_provisioning_limit": 99,
- "organization": {
- "__type__": "Organization",
- "allowed_email_domains": [
- "barker.co"
], - "domain": "barker-inc",
- "environments": [
- {
- "name": "production",
- "status": "down"
}, - {
- "name": "sandbox",
- "status": "up"
}
], - "inserted_at": "2023-06-08T12:12:28",
- "name": "Barker",
- "status": {
- "errors": [ ],
- "estimated_time_to_complete_in_seconds": null,
- "progress_in_percentage": null,
- "state": "pending"
}, - "updated_at": "2023-06-08T12:37:59"
}, - "provider_type": "saml.azure_ad",
- "saml_config": {
- "entity_id": "shark_academy_MgF6Z9maZKriEBbLM9KZJj",
- "sso_provider_metadata": null
}, - "sp_id": "shark_academy_MgF6Z9maZKriEBbLM9KZJj",
- "updated_at": "2023-06-08T13:47:41",
- "users_access_policy": "provision_new_users"
}
Before you can create an SSO challenge, you must first set up an SSO connection.
An SSO challenge is a secure validation process used in single sign-on (SSO). It requires the user to successfully complete an authentication request to verify their identity and gain access to SSO-protected services.
The SSO Challenge type
__environment__ | string The environment in which the user is stored, either sandbox (for the test environment) or production. |
__type__ | string The |
authorization_url | string URL used to redirect users to a page where they can provide consent during the authentication process. |
expired_at | integer The expiration date and time of the SSO challenge |
redirect_uri | string URL used to redirect the user after an interaction with a service or application. |
request_id | uuid Unique identifiers associated with the creation of an SSO challenge. It allows following this specific request throughout the single sign-on process. |
sso_connection_id | string The unique identifier of the SSO Connection used. |
{- "__environment__": "sandbox",
- "__type__": "SsoChallenge",
- "authorization_url": "https//your-cryptr-service-url.com/org/loirama/oauth2/saml?request_id=8d814d02-35d8-48a9-a033-291fd5959a0c",
- "expired_at": 1684774623,
- "request_id": "8d814d02-35d8-48a9-a033-291fd5959a0c",
- "sso_connection_id": "loirama_VqiFf3Y5ogaYRbyEyazDWn"
}
Create an SSO Challenge
Create an SSO Challenge to strengthen security and simplify user authentication.
RETURNS
Returns information such as the authorization URL
, the redirection URL
, and other identifiers associated with the Challenge SSO created.
query Parameters
redirect_uri required | string Example: redirect_uri=https://loirama.com/welcome-back-user URL used to redirect the user after an interaction with a service or application. |
user_email | string <email> Example: user_email=it_sso_person@sso.client.com The email address associated with the account or the identity of a user used for authentication and information exchange during the single sign-on process. Please note that either |
org_domain | string Example: org_domain=loirama The domain is a string value in lowercase with dashes, generated from the organization’s name. Please note that either |
Responses
Request samples
- cURL
- Java
- Node JS
- Kotlin
- PHP
- Python
- Ruby
curl -X POST '${cryptr_service_url}/api/v2/sso-saml-challenges' \ -d user_email="lyla@loirama.co" \ -d redirect_uri="https://loirama.com/welcome-back-user" \ // Use the following option if you prefer to use org_domain instead of user_email \ // -d org_domain="loirama"
Response samples
- 201
{- "__environment__": "sandbox",
- "__type__": "SsoChallenge",
- "authorization_url": "https//your-cryptr-service-url.com/org/loirama/oauth2/saml?request_id=8d814d02-35d8-48a9-a033-291fd5959a0c",
- "expired_at": 1684774623,
- "request_id": "8d814d02-35d8-48a9-a033-291fd5959a0c",
- "sso_connection_id": "loirama_VqiFf3Y5ogaYRbyEyazDWn"
}
Create an SSO Connection
Creates a new SSO connection type. The response automatically expands the onboarding
nested element.
RETURNS
Returns an SSO Connection if the creation succeeds.
path Parameters
org_domain required | string Example: well-agency The domain is a string value in lowercase with dashes, generated from the organization’s name. |
query Parameters
number_users_provisioning_limit | integer Change the limit of simultaneously possible SSO sessions for the targeted SSO Connection ⚠️ Depending on the |
users_access_policy | string Default: "provision_new_users" Enum: "only_registered_users" "provision_new_users" "unregistered_users_allowed" Example: users_access_policy=unregistered_users_allowed The Possible values for this key are:
|
active | boolean Default: true If you want to create it but not activate it for now |
Responses
Request samples
- cURL
- Java
- Node JS
- Kotlin
- PHP
- Python
- Ruby
curl -X POST '${cryptr_service_url}/api/v2/org/${org_domain}/sso-connection'
Response samples
- 201
{- "__type__": "SsoConnection",
- "active": true,
- "id": "barker_inc_S6f5ndf8mZqfoBKoxEotMV",
- "inserted_at": "2023-06-08T13:47:41",
- "number_users_provisioning_limit": 99,
- "organization": {
- "__type__": "Organization",
- "allowed_email_domains": [
- "barker.co"
], - "domain": "barker-inc",
- "environments": [
- {
- "name": "production",
- "status": "down"
}, - {
- "name": "sandbox",
- "status": "up"
}
], - "inserted_at": "2023-06-08T12:12:28",
- "name": "Barker",
- "status": {
- "errors": [ ],
- "estimated_time_to_complete_in_seconds": null,
- "progress_in_percentage": null,
- "state": "pending"
}, - "updated_at": "2023-06-08T12:37:59"
}, - "provider_type": "saml.azure_ad",
- "saml_config": {
- "entity_id": "shark_academy_MgF6Z9maZKriEBbLM9KZJj",
- "sso_provider_metadata": null
}, - "sp_id": "shark_academy_MgF6Z9maZKriEBbLM9KZJj",
- "updated_at": "2023-06-08T13:47:41",
- "users_access_policy": "provision_new_users"
}
List all SSO Connections
List all your SSO connections currently created, regardless of the progress of the configuration.
RETURNS
Returns list of SSO Connections with nested objects if preload_associations is set, and paginated if related attributes are present.
query Parameters
page | |
per_page | integer Example: per_page=2 Specify the size of the pages for pagination of the list. See how to paginate the Cryptr API. |
Responses
Request samples
- cURL
curl '${cryptr_service_url}/api/v2/sso-connections' -d page=${page} -d per_page=${per_page}
Response samples
- 200
{- "__type__": "List",
- "data": [
- {
- "__type__": "SsoConnection",
- "id": "barker_inc_ENbw8MukSNtTKCqPZC2U7g",
- "inserted_at": "2023-06-09T14:23:09",
- "number_users_provisioning_limit": 99,
- "organization": {
- "__type__": "Organization",
- "allowed_email_domains": [
- "barker.co"
], - "domain": "barker-inc",
- "environments": [
- {
- "name": "production",
- "status": "down"
}, - {
- "name": "sandbox",
- "status": "up"
}
], - "inserted_at": "2023-06-08T12:12:28",
- "name": "Barker",
- "status": {
- "errors": [ ],
- "estimated_time_to_complete_in_seconds": null,
- "progress_in_percentage": null,
- "state": "pending"
}, - "updated_at": "2023-06-08T12:37:59"
}, - "provider_type": "saml.azure_ad",
- "saml_config": {
- "entity_id": "shark_academy_MgF6Z9maZKriEBbLM9KZJj",
- "sso_provider_metadata": null
}, - "sp_id": "shark_academy_MgF6Z9maZKriEBbLM9KZJj",
- "updated_at": "2023-06-09T14:23:09",
- "users_access_policy": "provision_new_users"
}, - {
- "__type__": "SsoConnection",
- "id": "looney_tunes_gNT8hCyC7MsovKaLFWnSUh",
- "inserted_at": "2023-05-26T07:22:47",
- "number_users_provisioning_limit": null,
- "organization": {
- "__type__": "Organization",
- "allowed_email_domains": [
- "Looney_tunes.co"
], - "domain": "looney-tunes",
- "environments": [
- {
- "name": "sandbox",
- "status": "up"
}, - {
- "name": "production",
- "status": "up"
}
], - "inserted_at": "2023-05-26T07:21:20",
- "name": "Looney tunes",
- "status": {
- "errors": [ ],
- "estimated_time_to_complete_in_seconds": null,
- "progress_in_percentage": null,
- "state": "pending"
}, - "updated_at": "2023-05-26T07:21:40"
}, - "provider_type": "unset",
- "saml_config": {
- "entity_id": "shark_academy_MgF6Z9maZKriEBbLM9KZJj",
- "sso_provider_metadata": null
}, - "sp_id": "shark_academy_MgF6Z9maZKriEBbLM9KZJj",
- "updated_at": "2023-05-26T07:22:47",
- "users_access_policy": "provision_new_users"
}
], - "pagination": {
- "current_page": 1,
- "current_pages": [
- 1,
- 2,
- 3,
- "...",
- 26
], - "next_page": 2,
- "per_page": 2,
- "prev_page": null,
- "total_pages": 26
}, - "total": 52
}
Retrieve an SSO Connection
Fetch an SSO connection, useful to know its configuration and also fetch nested object onboarding
.
RETURNS
Returns the SSO Connection
path Parameters
org_domain required | string Example: lalylala The domain is a string value in lowercase with dashes, generated from the organization’s name. |
Responses
Request samples
- cURL
curl '${cryptr_service_url}/api/v2/org/${org_domain}/sso-connection'
Response samples
- 200
{- "__type__": "SsoConnection",
- "active": true,
- "id": "barker_inc_S6f5ndf8mZqfoBKoxEotMV",
- "inserted_at": "2023-06-08T13:47:41",
- "number_users_provisioning_limit": 99,
- "organization": {
- "__type__": "Organization",
- "allowed_email_domains": [
- "barker.co"
], - "domain": "barker-inc",
- "environments": [
- {
- "name": "production",
- "status": "down"
}, - {
- "name": "sandbox",
- "status": "up"
}
], - "inserted_at": "2023-06-08T12:12:28",
- "name": "Barker",
- "status": {
- "errors": [ ],
- "estimated_time_to_complete_in_seconds": null,
- "progress_in_percentage": null,
- "state": "pending"
}, - "updated_at": "2023-06-08T12:37:59"
}, - "provider_type": "saml.azure_ad",
- "saml_config": {
- "entity_id": "shark_academy_MgF6Z9maZKriEBbLM9KZJj",
- "sso_provider_metadata": null
}, - "sp_id": "shark_academy_MgF6Z9maZKriEBbLM9KZJj",
- "updated_at": "2023-06-08T13:47:41",
- "users_access_policy": "provision_new_users"
}
Update an SSO Connection
Fetch an SSO connection, useful to know its configuration and also fetch nested object onboarding
.
RETURNS
Returns the updated SSO Connection
path Parameters
org_domain required | string Example: lalylala The domain is a string value in lowercase with dashes, generated from the organization’s name. |
query Parameters
active | boolean Example: active=true Change the state of the SSO Connection to enable/disable requests. |
metadata | string Example: metadata=3d5245f2-194a-498c-ad28-736ca9fffb3b This should be the XML metadata string content. If you want to change the XML for the targeted Sso Connection. For example, if the SSO administrator sends you a new XML metadata for the connection, you can update it here. |
number_users_provisioning_limit | integer Change the limit of simultaneously possible SSO sessions for the targeted SSO Connection ⚠️ Depending on the |
users_access_policy | string Example: users_access_policy=provision_new_users Change the rule for end-user session opening for the targeted SSO Connection |
preload_associations | Array of strings By default, all nested resources are returned by their IDs. If you would like the nested object to be returned in the body, you can set the |
Responses
Request samples
- cURL
curl -X PUT 'https://${YOUR_CRYPTR_SERVICE_URL}/api/v2/sso-connections/:idp_id' \ --header 'Authorization: Bearer your_api_key_generated_token' \ --header 'Content-Type: application/json' \ --data-raw '{ "number_users_provisioning_limit": 99 }'
Response samples
- 200
{- "__type__": "SsoConnection",
- "active": true,
- "id": "barker_inc_S6f5ndf8mZqfoBKoxEotMV",
- "inserted_at": "2023-06-08T13:47:41",
- "number_users_provisioning_limit": 99,
- "organization": {
- "__type__": "Organization",
- "allowed_email_domains": [
- "barker.co"
], - "domain": "barker-inc",
- "environments": [
- {
- "name": "production",
- "status": "down"
}, - {
- "name": "sandbox",
- "status": "up"
}
], - "inserted_at": "2023-06-08T12:12:28",
- "name": "Barker",
- "status": {
- "errors": [ ],
- "estimated_time_to_complete_in_seconds": null,
- "progress_in_percentage": null,
- "state": "pending"
}, - "updated_at": "2023-06-08T12:37:59"
}, - "provider_type": "saml.azure_ad",
- "saml_config": {
- "entity_id": "shark_academy_MgF6Z9maZKriEBbLM9KZJj",
- "sso_provider_metadata": null
}, - "sp_id": "shark_academy_MgF6Z9maZKriEBbLM9KZJj",
- "updated_at": "2023-06-08T13:47:41",
- "users_access_policy": "provision_new_users"
}
Headless Password Challenges
Password challenge is a secure validation process for password. It involves an authentication request sent to the user, who must pass a challenge to prove his identity and access protected services.
The Password Challenge type
__domain__ | string The domain is a string value in lowercase with dashes, generated from the organization’s name. |
__environment__ | string The environment in which the user is stored, either sandbox (for the test environment) or production. |
__type__ | string The |
code | string The code retrieves the AccessToken for the user. |
error | string Description of an error encountered during the challenge process |
expired_at | integer The expiration date and time of the Password challenge |
password_id | integer The immutable identifier of the actual Password |
renew_password | object (PasswordChallenge) Recursive If the password of the user is expired a renew_password map will be displayed to help you renew the password. |
request_id | uuid The ID of the request |
user_id | uuid The immutable identifier of the User |
valid? | boolean The validity of the Password challenge |
{- "__domain__": "loirama",
- "__environment__": "production",
- "__type__": "PasswordChallenge",
- "code": "iIsImlzcyI6Imh0dHA6Ly9sb2NhbGhvc3Q6NDAwMC90L2Jsb2NrcHVsc2UiLCJraWQ",
- "error": null,
- "expired_at": null,
- "password_id": 145,
- "renew_password": null,
- "request_id": "edead972-68e1-49ea-8257-c0584cded957",
- "user_id": "37a4c183-8e33-43aa-8c0d-ea7bbc648bf1",
- "valid?": true
}
Password Connections
You can create or update Password connection preferences for an Organization (usualy your Enterprise customer).
The Password Connection type
__domain__ | string The domain is a string value in lowercase with dashes, generated from the organization’s name. |
__type__ | string The |
active | boolean Default: true Specify if the connection is usable. |
id | string The immutable identifier. |
inserted_at | string <date-time> Date time of the insertion |
pepper_rotation_period | integer The time period between each pepper rotation. |
plain_text_max_length | integer The maximum length of the plain text (password). |
plain_text_min_length | integer The minimum length of the plain text (password). |
updated_at | string <date-time> Update timestamp |
{- "__domain__": "shark-academy",
- "__type__": "PasswordConnection",
- "active": true,
- "id": "b6f3da01-b571-48c3-a630-6f1fddf5af31",
- "inserted_at": "2023-06-08T13:47:41",
- "pepper_rotation_period": 86400,
- "plain_text_max_length": 40,
- "plain_text_min_length": 8,
- "updated_at": "2023-06-08T13:47:41"
}
Headless Passwords
You can create, reset or renew a Password for an User.
The Headless Passwords type
__domain__ | string The domain is a string value in lowercase with dashes, generated from the organization’s name. |
__environment__ | string The environment in which the user is stored, either sandbox (for the test environment) or production. |
__type__ | string The |
code | string The code used to retrieve the User AccessToken |
id | integer The immutable identifier of the new password |
user_id | uuid The immutable identifier of the User |
{- "__domain__": "loirama",
- "__environment__": "production",
- "__type__": "Password",
- "code": "DqwZQU8umrgLBAZXEPRiizjOCpzQJgTXwWya6dX3cXkpESDAgqcgTYKq0TPFeYt6MCv5l1pcg8ySB6FJmNhyA5WhHYyVlQXs2udx",
- "id": 145,
- "user_id": "9e6e2777-d2bb-42cb-bb7a-13139358d7fa"
}
Create a new Password
Create a Password (Renew, Reset, First Creation). You can use this endpoint with a password_code or without it. The password_code is a code that we will send you to allow you to reset the password of the user. You will obtain this code by performing a Password Request or by processing a PasswordChallenge for which the password has expired. If you don't want to use the password_code. Don't include the key in your query.
RETURNS
A Struct giving data about the new password.
query Parameters
org_domain required | string Example: org_domain=loirama The domain is a string value in lowercase with dashes, generated from the organization’s name. |
user_email required | string <email> Example: user_email=it_person@client.com The email address associated with the account or the identity of a user used for authentication and information exchange during the sign-in or sign-up process. |
password_code | string Example: password_code=Zef785dkHgd The password code that we will send to you when the user's Password is expired when Password Challenge is processed or when you request a reset. If you don't want to use a password_code you can use the same endpoint without the password_code key in your query. |
plain_text required | string Example: plain_text=neripe7845sjHgdeje! The new password of the user as plain text. |
Responses
Request samples
- cURL
- Java
- Node JS
- Kotlin
- PHP
- Python
- Ruby
curl -X POST '${cryptr_service_url}/api/v2/renew-password' \ -d user_email="lyla@loirama.co" \ -d password_code="jf78Hgdz5d" \ -d plain_text="neripe7845sjHgdeje!" \ -d org_domain="communitiz-app"
Response samples
- 201
- 422
{- "__domain__": "loirama",
- "__environment__": "production",
- "__type__": "Password",
- "code": "DqwZQU8umrgLBAZXEPRiizjOCpzQJgTXwWya6dX3cXkpESDAgqcgTYKq0TPFeYt6MCv5l1pcg8ySB6FJmNhyA5WhHYyVlQXs2udx",
- "id": 145,
- "user_id": "9e6e2777-d2bb-42cb-bb7a-13139358d7fa"
}
Create a Password Challenge
Create a Password Challenge to strengthen security and simplify user authentication.
RETURNS
Returns information such as the request_id
, renew_code
, the validity, and other information associated with the Challenge created.
query Parameters
org_domain | string Example: org_domain=loirama The domain is a string value in lowercase with dashes, generated from the organization’s name. Please note that |
user_email required | string <email> Example: user_email=it_person@client.com The email address associated with the account or the identity of a user used for authentication and information exchange during the sign-in or sign-up process. Please note that |
plain_text required | string Example: plain_text=neripe7845sjHgdeje! The password of the user as plain text. |
Responses
Request samples
- cURL
- Java
- Node JS
- Kotlin
- PHP
- Python
- Ruby
curl -X POST '${cryptr_service_url}/api/v2/password-challenge' \ -d user_email="lyla@loirama.co" \
Response samples
- 201
- 404
{- "__domain__": "loirama",
- "__environment__": "production",
- "__type__": "PasswordChallenge",
- "code": "iIsImlzcyI6Imh0dHA6Ly9sb2NhbGhvc3Q6NDAwMC90L2Jsb2NrcHVsc2UiLCJraWQ",
- "error": null,
- "expired_at": null,
- "password_id": 145,
- "renew_password": null,
- "request_id": "edead972-68e1-49ea-8257-c0584cded957",
- "user_id": "37a4c183-8e33-43aa-8c0d-ea7bbc648bf1",
- "valid?": true
}
Create a Password Connection
Creates a new Password Connection. This will enable password login for users and allow you to configure it.
RETURNS
Returns a Password Connection if the creation succeed.
path Parameters
org_domain required | string Example: well-agency The domain is a string value in lowercase with dashes, generated from the organization’s name. |
query Parameters
plain_text_max_length | integer Example: plain_text_max_length=20 The maximum length of the password (should be higher than the minimum length) |
plain_text_min_length | integer Example: plain_text_min_length=8 The minimum length of the password (should be lower than the maximum length) |
active | boolean Default: true If you want to create but not activate it for now |
Responses
Request samples
- cURL
- Java
- Node JS
- Kotlin
- PHP
- Python
- Ruby
curl -X POST '${cryptr_service_url}/api/v2/org/${org_domain}/password-connection'
Response samples
- 201
- 422
{- "__domain__": "shark-academy",
- "__type__": "PasswordConnection",
- "active": true,
- "id": "b6f3da01-b571-48c3-a630-6f1fddf5af31",
- "inserted_at": "2023-06-08T13:47:41",
- "pepper_rotation_period": 86400,
- "plain_text_max_length": 40,
- "plain_text_min_length": 8,
- "updated_at": "2023-06-08T13:47:41"
}
Request a new Password via Magic Link
Request a new Password. This endpoint is useful when the password is leaked, forgot or when you want to create the first password of the user.
RETURNS
A Struct giving data about the password Request. Including the Magic Link Token that you will have to send to the user to reset or create his password.
query Parameters
org_domain required | string Example: org_domain=loirama The domain is a string value in lowercase with dashes, generated from the organization’s name. |
user_email required | string <email> Example: user_email=it_person@client.com The email address associated with the account or the identity of a user used for authentication and information exchange during the sign-in or sign-up process. |
redirect_uri required | string Example: redirect_uri=https://loirama.com/welcome-back-user URL used to redirect the user after an interaction with a service or application. |
find_or_create_user | boolean Default: false Example: find_or_create_user=true Flag that finds OR creates the user.
|
Responses
Request samples
- cURL
- Java
- Node JS
- Kotlin
- PHP
- Python
- Ruby
curl -X POST '${cryptr_service_url}/api/v2/password-request' \ -d user_email="lyla@loirama.co" \ -d org_domain="communitiz-app" \ -d redirect_uri="https://loirama.com/welcome-back-user"
Response samples
- 201
- 500
{- "__domain__": "loirama",
- "__environment__": "production",
- "__type__": "PasswordRequest",
- "expired_at": "2023-05-04T07:16:56",
- "request_id": "4db191b5-6209-4358-9d09-a28b8a8eaab5",
- "user_id": "d6a46443-c7bc-4259-aa5d-ce51cc548b57"
}
Retrieve a Password Connection
Retrieve a Password Connection for an Organization by providing the org_domain
.
This request allowes you to obtain information about an existing Password Connection associated with the specified Organization.
RETURNS
If the reques is successful, the API returns an object representing the retrieved Password Connection
path Parameters
org_domain required | string Example: loirama The domain is a string value in lowercase with dashes, generated from the organization’s name. |
Responses
Request samples
- cURL
curl '${cryptr_service_url}/api/v2/org/${org_domain}/password-connection'
Response samples
- 200
{- "__domain__": "shark-academy",
- "__type__": "PasswordConnection",
- "active": true,
- "id": "b6f3da01-b571-48c3-a630-6f1fddf5af31",
- "inserted_at": "2023-06-08T13:47:41",
- "pepper_rotation_period": 86400,
- "plain_text_max_length": 40,
- "plain_text_min_length": 8,
- "updated_at": "2023-06-08T13:47:41"
}
Update a Password Connection
path Parameters
org_domain required | string Example: loirama The domain is a string value in lowercase with dashes, generated from the organization’s name. |
query Parameters
active | boolean Example: active=false Allows you to activate or disable this password connection for your authentication processes of the selected Organization Set |
Responses
Request samples
- cURL
curl -X PUT '${cryptr_service_url}/api/v2/org/${org_domain}/password-connection' \ -d active=false
Response samples
- 200
{- "__domain__": "shark-academy",
- "__type__": "PasswordConnection",
- "active": false,
- "id": "b6f3da01-b571-48c3-a630-6f1fddf5af31",
- "inserted_at": "2023-06-08T13:47:41",
- "pepper_rotation_period": 86400,
- "plain_text_max_length": 40,
- "plain_text_min_length": 8,
- "updated_at": "2023-06-08T13:47:41"
}
Magic Link Connection
Cryptr provides a secure solution for creating, managing, updating, and deleting connections using magic links. These magic links enable passwordless authentication, simplifying the login process while enhancing security.
Magic Link Connections can be set to specific organizations' environments, allowing user registration or restricting access to registered users. You can customize the magic link emails by providing template IDs for personalized sign-up experiences.
The Magic Link Connection type
__type__ | string Data type |
active | boolean Default: true Specify if the connection is usable. |
find_or_create_user | boolean Default: false Flag that finds or creates the user.
|
id | uuid The unique identifier |
inserted_at | string <date-time> Insertion datetime |
sign_in_template_id | uuid The unique identifier of the email template to use. There are three possible cases:
|
updated_at | string <date-time> Update datetime |
{- "__type__": "string",
- "active": true,
- "find_or_create_user": false,
- "id": null,
- "inserted_at": "2019-08-24T14:15:22Z",
- "sign_in_template_id": null,
- "updated_at": "2019-08-24T14:15:22Z"
}
The Magic Link Challenge type
__domain__ | string The domain is a string value in lowercase with dashes, generated from the organization’s name. |
__environment__ | string The environment in which the user is stored, either sandbox (for the test environment) or production. |
__type__ | string The |
code | string The code retrieves the AccessToken for the user. |
email_address | string The email address of the user. |
find_or_create_user | boolean Default: false Flag that finds or creates the user.
|
magic_link | string The Magic Link sent to the user via email. |
request_id | string The ID of the request |
{- "__domain__": "loirama",
- "__environment__": "production",
- "__type__": "MagicLinkChallenge",
- "code": null,
- "email_address": "random@gmail.com",
- "find_or_create_user": true,
- "request_id": null
}
Create a Magic Link Challenge
Create a Magic Link Challenge to simplify user authentication.
RETURNS
Returns information such as the email_address
, the Magic Link, and other information associated with the Challenge created.
query Parameters
org_domain | string Example: org_domain=loirama The domain is a string value in lowercase with dashes, generated from the organization’s name. Please note that |
user_email required | string <email> Example: user_email=it_person@client.com The email address associated with the account or the identity of a user used for authentication and information exchange during the sign-in or sign-up process. Please note that |
redirect_uri required | string Example: redirect_uri=https://loirama.com/welcome-back-user URL used to redirect the user after an interaction with a service or application. |
Responses
Request samples
- cURL
- Java
- Node JS
- Kotlin
- PHP
- Python
- Ruby
curl -X POST '${cryptr_service_url}/api/v2/magic-link-challenge' \ -d user_email="lyla@loirama.co" \ -d redirect_uri="https://loirama.com/welcome-back-user"
Response samples
- 201
- 404
{- "__domain__": "loirama",
- "__environment__": "production",
- "__type__": "MagicLinkChallenge",
- "code": null,
- "email_address": "random@gmail.com",
- "find_or_create_user": true,
- "request_id": null
}
Retrieve a Magic Link Connection
Retrieve a Magic Link Connection for an Organization by providing the org_domain
. This request allows you to obtain information about an existing Magic Link Connection associated with the specified organization.
RETURNS
If the request is successful, the API returns an object representing the retrieved Magic Link Connection.
path Parameters
org_domain required | string Example: loirama The domain is a string value in lowercase with dashes, generated from the organization’s name. |
Responses
Request samples
- cURL
curl '${cryptr_service_url}/api/v2/org/${org_domain}/magic-link-connection'
Response samples
- 200
{- "__type__": "MagicLinkConnection",
- "active": true,
- "find_or_create_user": false,
- "id": "b6f3da01-b571-48c3-a630-6f1fddf5af31",
- "inserted_at": "2023-06-08T13:47:41",
- "sign_in_template_id": "b653df01-b571-48c3-a630-6f1fddf5af31",
- "updated_at": "2023-06-08T13:47:41"
}
Update a Magic Link Connection
Update a Magic Link Connection for an Organization by providing the org_domain
, and modify the find_or_create_user
key to determine whether to automatically register users on their first login or restrict access to existing users.
RETURNS
If the request is successful, the API returns an updated MagicLinkConnection object, confirming the modifications made to the Magic Link Connection for the specified organization.
path Parameters
org_domain required | string Example: loirama The domain is a string value in lowercase with dashes, generated from the organization’s name. |
query Parameters
find_or_create_user | boolean Default: false Example: find_or_create_user=true Flag that finds OR creates the user.
|
active | boolean Example: active=true Allows you to activate or disable this MagicLinkConnection for authentication processes within the selected organization. Set to |
Responses
Request samples
- cURL
curl -X PUT '${cryptr_service_url}/api/v2/org/${org_domain}/magic-link-connection' \ -d find_or_create_user=${find_or_create_user} \ -d active=${active} \
Response samples
- 200
{- "__type__": "MagicLinkConnection",
- "active": true,
- "find_or_create_user": false,
- "id": "b6f3da01-b571-48c3-a630-6f1fddf5af31",
- "inserted_at": "2023-06-08T13:47:41",
- "sign_in_template_id": "b653df01-b571-48c3-a630-6f1fddf5af31",
- "updated_at": "2023-06-08T13:47:41"
}
Headless TOTP Challenges
TOTP challenge is a secure validation process for TOTP. It involves an authentication request sent to the user, who must pass a challenge to prove their identity and access protected services.
The TOTP Challenge type
__type__ | string The |
challenged_at | string The date on which the challenge validation took place. |
code | boolean Default: false The code that the user entered. |
recovery_code_used | boolean Default: false If a recovery code was used for the TOTP challenge, the value will be true. If so, you should re-enroll your user. |
request_id | string The unique identifier of the request; creation and validation have different request_ids. |
sent_at | string The date when the challenge was created. |
success | boolean The success status of the challenge. It will be false at creation and should be true at validation. |
{- "__type__": "TotpChallenge",
- "challenged_at": null,
- "code": null,
- "recovery_code_used": false,
- "request_id": null,
- "sent_at": null,
- "success": true
}
TOTP Connections
You can create or update TOTP connection preferences for an organization (usually your enterprise customer).
The TOTP Connection type
__domain__ | string The domain is a string value in lowercase with dashes, generated from the organization’s name. |
active | boolean Determines if the connection is active. |
expiry_in_seconds | integer The expiration time of the TOTP is 30 seconds by default for the TOTP Mobile App and 600 seconds for SMS. |
method | string The method you want to use (SMS or TOTP Mobile App, default). |
{- "__domain__": "loirama",
- "active": true,
- "expiry_in_seconds": 600,
- "method": "sms"
}
TOTP Enrollment
You can enroll your users in TOTP.
The TOTP Enrollment type
__domain__ | string The domain is a string value in lowercase with dashes, generated from the organization’s name. |
__environment__ | string The environment in which the user is stored, either sandbox (for the test environment) or production. |
__type__ | string The |
string The email of the user for which an enrollment is requested. | |
enrolled_totp_at | string The date on which the enrollment was created. |
enrollment_totp_nb | integer The number of enrollments for a user. |
first_verification_code | string The code that the user should use for SMS enrollment validation. It is only displayed during creation for the SMS method. |
last_recovery_acknowledgement_at | string The last date on which the user acknowledged receipt of their recovery codes. |
last_recovery_code_at | string The last date on which the user used a recovery code. |
recovery_codes | string The user's recovery codes. These codes are generated only once unless the user is force-enrolled. Each code is separated by '\n' |
uri | string The URI that should be used to enroll in a mobile TOTP app. This is only displayed for the TOTP Mobile App method. |
validated_enrollment_at | string The date on which the enrollment was validated. |
{- "__domain__": "loirama",
- "__environment__": "production",
- "__type__": "TotpEnrollment",
- "email": "jean@loirama.com",
- "enrolled_totp_at": "2023-08-23T09:32:42",
- "enrollment_totp_nb": 1,
- "first_verification_code": "935885",
- "last_recovery_acknowledgement_at": null,
- "last_recovery_code_at": null,
- "recovery_codes": "b8JS-04VLtcY-5LVXqG_\nW9-9BnAwd2Wvt4928V1q\nZxB29DgffU7QiAAZp6-b\nrvUxePOaZIEM6U69-mpS\nsZqbtudhH9QmY_pepbkp",
- "uri": null,
- "validated_enrollment_at": null
}
Create a TOTP Challenge
Create a TOTP Challenge to enhance security, specifically useful for the SMS method to generate a code and send it to your users via SMS.
RETURNS
Returns information such as the request_id
, code
, validity, and other details associated with the created challenge.
path Parameters
org_domain required | string Example: loirama The domain is a string value in lowercase with dashes, generated from the organization’s name. Please note that |
user_id required | uuid Example: 0d34d179-8a81-49e8-b572-289d0e522691 User immutable identifier |
Responses
Request samples
- cURL
- Java
- Node JS
- Kotlin
- PHP
- Python
- Ruby
curl -X POST '${cryptr_service_url}/api/v2/org/${org_domain}/totp-challenge/:user_id'
Response samples
- 201
- 403
- 404
- 422
{- "__type__": "TotpChallenge",
- "challenged_at": null,
- "code": "044416",
- "recovery_code_used": false,
- "request_id": "totp-challenge_2ULQqKdMOFwJ0HJfR8rTt1f1kxv",
- "sent_at": "2023-08-22T15:02:50.101028",
- "success": false
}
Create a TOTP Enrollment
Create a TOTP enrollment to register a user for MFA (TOTP).
RETURNS
Returns information such as enrollment_nb
, enrolled_at
, validity, and other details associated with the created enrollment.
path Parameters
org_domain required | string Example: loirama The domain is a string value in lowercase with dashes, generated from the organization’s name. Please note that both |
user_id required | uuid Example: 0d34d179-8a81-49e8-b572-289d0e522691 User immutable identifier |
force_enroll | boolean Default: false Example: true If you want to re-enroll a user, even if they have used all their recovery codes, set this value to true. Additionally, generate five new recovery codes upon activation. |
Responses
Request samples
- cURL
- Java
- Node JS
- Kotlin
- PHP
- Python
- Ruby
curl -X POST '${cryptr_service_url}/api/v2/org/${org_domain}/totp-enrollment/:user_id' \ -d force_enroll='false'
Response samples
- 201
- 404
{- "__domain__": "loirama",
- "__environment__": "production",
- "__type__": "TotpEnrollment",
- "email": "jean@loirama.com",
- "enrolled_totp_at": "2023-08-23T09:32:42",
- "enrollment_totp_nb": 1,
- "first_verification_code": "935885",
- "last_recovery_acknowledgement_at": null,
- "last_recovery_code_at": null,
- "recovery_codes": "b8JS-04VLtcY-5LVXqG_\nW9-9BnAwd2Wvt4928V1q\nZxB29DgffU7QiAAZp6-b\nrvUxePOaZIEM6U69-mpS\nsZqbtudhH9QmY_pepbkp",
- "uri": null,
- "validated_enrollment_at": null
}
Retrieve a TOTP Connection
Retrieve a TOTP Connection for an Organization by specifying the org_domain
. By default, organizations own a TOTP Connection, but it is deactivated.
RETURNS
If the request is successful, the API returns a TOTP object with an identifier including all the information associated with it.
path Parameters
org_domain required | string Example: loirama The domain is a string value in lowercase with dashes, generated from the organization’s name. |
Responses
Request samples
- cURL
- Java
- Node JS
- Kotlin
- PHP
- Python
- Ruby
curl -X GET '${cryptr_service_url}/api/v2/org/${org_domain}/totp-connection
Response samples
- 200
{- "__domain__": "loirama",
- "active": true,
- "expiry_in_seconds": 600,
- "method": "sms"
}
Update a TOTP Connection
Update a TOTP Connection for an Organization by specifying the org_domain
. By default, organizations own a TOTP Connection, but it is deactivated.
RETURNS
If the request is successful, the API returns a TOTP object with an identifier including all the information entered.
path Parameters
org_domain required | string Example: loirama The domain is a string value in lowercase with dashes, generated from the organization’s name. |
query Parameters
active | boolean Default: false Example: active=true Boolean that determines whether your TOTP strategy should be enabled or disabled. |
expiry_in_seconds | integer Default: 30 Example: expiry_in_seconds=600 OTP code expiration time in seconds. Default is 600 seconds for SMS method (10 minutes) and 30 seconds for the mobile app method. The maximum validity of a TOTP is 900 seconds (15 minutes), and its minimum duration is 30 seconds. Note that most mobile applications have a TOTP duration of 30 seconds. Therefore, it is strongly recommended to keep the default validity time for the mobile app method. |
method | string Default: "totp_mobile_app" Example: method=sms Determines the method to be used. Allowed methods are |
Responses
Request samples
- cURL
- Java
- Node JS
- Kotlin
- PHP
- Python
- Ruby
curl -X POST '${cryptr_service_url}/api/v2/org/${org_domain}/totp-connection' \ -d active='true' \ -d expiry_in_seconds='30' \ -d method='totp_mobile_app'
Response samples
- 201
- 422
{- "__domain__": "loirama",
- "active": true,
- "expiry_in_seconds": 600,
- "method": "sms"
}
Validate a TOTP Challenge
Validate a TOTP Challenge by checking the code the user enters on your app.
RETURNS
Returns information such as the request_id
, code
, the validity, and other information associated with the Challenge.
path Parameters
org_domain required | string Example: loirama The domain is a string value in lowercase with dashes, generated from the organization’s name. Please note that |
user_id required | uuid Example: 0d34d179-8a81-49e8-b572-289d0e522691 User immutable identifier |
query Parameters
code required | string Example: code=478562 The user's TOTP code as plain text. |
Responses
Request samples
- cURL
- Java
- Node JS
- Kotlin
- PHP
- Python
- Ruby
curl -X PUT '${cryptr_service_url}/api/v2/org/${org_domain}/totp-challenge/validation/:user_id' \ -d code='478562'
Response samples
- 201
- 401
- 403
- 404
- 422
{- "__type__": "TotpChallenge",
- "challenged_at": "2023-08-22T15:00:55.816432",
- "code": "008029",
- "recovery_code_used": false,
- "request_id": "totp-challenge_2ULQbzNww3R4ANIZyroXwYsS8Wg",
- "sent_at": null,
- "success": true
}
Validate a TOTP Enrollment
Validate a TOTP enrollment by checking the code the user enters in your app. If the user is able to enter a valid code, we assume that they have registered their QR Code in their TOTP application or that their phone number is valid.
RETURNS
Returns information such as the enrollment_nb
, enrolled_at
, the validity, and other information associated with the enrollment.
path Parameters
org_domain required | string Example: loirama The domain is a string value in lowercase with dashes, generated from the organization’s name. Please note that both |
user_id required | uuid Example: 0d34d179-8a81-49e8-b572-289d0e522691 User immutable identifier |
query Parameters
code required | string Example: code=478562 The user's TOTP code as plain text. |
Responses
Request samples
- cURL
- Java
- Node JS
- Kotlin
- PHP
- Python
- Ruby
curl -X PUT '${cryptr_service_url}/api/v2/org/${org_domain}/totp-enrollment/validation/:user_id' \ -d code='478562'
Response samples
- 200
- 401
- 404
{- "__domain__": "loirama",
- "__environment__": "production",
- "__type__": "TotpEnrollment",
- "email": "jean@loirama.com",
- "enrolled_totp_at": "2023-08-23T09:32:42",
- "enrollment_totp_nb": 1,
- "first_verification_code": null,
- "last_recovery_acknowledgement_at": null,
- "last_recovery_code_at": null,
- "recovery_codes": "b8JS-04VLtcY-5LVXqG_\nW9-9BnAwd2Wvt4928V1q\nZxB29DgffU7QiAAZp6-b\nrvUxePOaZIEM6U69-mpS\nsZqbtudhH9QmY_pepbkp",
- "uri": null,
- "validated_enrollment_at": "2023-08-23T09:34:50"
}
The Admin type
When you have the email contact of the SSO manager of the organization you want to work with, an Admin can be created. This Admin will be able to configure the SSO on their side by accessing the Onboarding.
Once created, the Admin will directly receive a magic link email to their onboarding.
accepted_invitation_at | string or null <date-time> Date and time when the Admin accepted the invitation. |
color | string The Admin's Logo Color in the Dashboard. |
declined_to_be_in_charge_at | string or null <date-time> Date and time when the admin declined to be in charge. |
string <email> Administrator's Email | |
id | uuid The immutable identifier |
inserted_at | string <date-time> Insertion datetime |
invited_at | string <date-time> The date and time the Admin was invited (creation date). |
last_login_at | string or null <date-time> Date and time of the Admin's last login. |
object (Organization) The Organization type | |
updated_at | string <date-time> Update timestamp |
{- "accepted_invitation_at": null,
- "color": "red-500",
- "declined_to_be_in_charge_at": null,
- "email": "it_sso_person@sso.client.com",
- "id": "64a13b92-e635-4931-a96f-5312fe3ba418",
- "inserted_at": "2023-06-09T16:22:44",
- "invited_at": "2023-06-09T16:22:44",
- "last_login_at": null,
- "organization": {
- "__type__": "Organization",
- "allowed_email_domains": [
- "barker.co"
], - "domain": "barker-inc",
- "environments": [
- {
- "name": "production",
- "status": "down"
}, - {
- "name": "sandbox",
- "status": "up"
}
], - "inserted_at": "2023-06-08T12:12:28",
- "name": "Barker",
- "status": {
- "errors": [ ],
- "estimated_time_to_complete_in_seconds": null,
- "progress_in_percentage": null,
- "state": "pending"
}, - "updated_at": "2023-06-08T12:37:59"
}, - "updated_at": "2023-06-09T16:22:44"
}
Create the Admin
See the Admin type for more information about the fields and their values you receive in the response.
An invitation link with a long TTL is sent to the Admin by email upon creation.
RETURNS
The created Admin with proper attributes
path Parameters
org_domain required | string Example: shark-academy The domain is a string value in lowercase with dashes, generated from the organization’s name. |
query Parameters
email required | string <email> Example: email=it_sso_person@sso.client.com The email of the admin of your client that has access to the onboarding. |
Responses
Request samples
- cURL
curl -X POST ${cryptr_service_url}/api/v2/org/${org_domain}/admins
Response samples
- 201
- 401
{- "accepted_invitation_at": null,
- "color": "red-500",
- "declined_to_be_in_charge_at": null,
- "email": "it_sso_person@sso.client.com",
- "id": "64a13b92-e635-4931-a96f-5312fe3ba418",
- "inserted_at": "2023-06-09T16:22:44",
- "invited_at": "2023-06-09T16:22:44",
- "last_login_at": null,
- "organization": {
- "__type__": "Organization",
- "allowed_email_domains": [
- "barker.co"
], - "domain": "barker-inc",
- "environments": [
- {
- "name": "production",
- "status": "down"
}, - {
- "name": "sandbox",
- "status": "up"
}
], - "inserted_at": "2023-06-08T12:12:28",
- "name": "Barker",
- "status": {
- "errors": [ ],
- "estimated_time_to_complete_in_seconds": null,
- "progress_in_percentage": null,
- "state": "pending"
}, - "updated_at": "2023-06-08T12:37:59"
}, - "updated_at": "2023-06-09T16:22:44"
}
Delete an Admin
path Parameters
org_domain required | string Example: loirama The domain is a string value in lowercase with dashes, generated from the organization’s name. |
email required | string Example: it_sso_person@sso.client.com The email of your Admin |
Responses
Request samples
- cURL
curl -X DELETE '${cryptr_service_url}/api/v2/org/${org_domain}/admins/${email}'
Response samples
- 200
- 401
- 404
{- "deleted": true,
- "resource": {
- "accepted_invitation_at": null,
- "color": "red-500",
- "declined_to_be_in_charge_at": null,
- "email": "it_sso_person@sso.client.com",
- "id": "64a13b92-e635-4931-a96f-5312fe3ba418",
- "inserted_at": "2023-06-09T16:22:44",
- "invited_at": "2023-06-09T16:22:44",
- "last_login_at": null,
- "organization": {
- "__type__": "Organization",
- "allowed_email_domains": [
- "barker.co"
], - "domain": "barker-inc",
- "environments": [
- {
- "name": "production",
- "status": "down"
}, - {
- "name": "sandbox",
- "status": "up"
}
], - "inserted_at": "2023-06-08T12:12:28",
- "name": "Barker",
- "status": {
- "errors": [ ],
- "estimated_time_to_complete_in_seconds": null,
- "progress_in_percentage": null,
- "state": "pending"
}, - "updated_at": "2023-06-08T12:37:59"
}, - "updated_at": "2023-06-09T16:22:44"
}
}
List all Admins
Returns a list of your Admins. The Admins are returned sorted by creation date, with the most recent appearing first.
RETURNS
A dictionary with a data
property that contains an array of up to limit
Admins. Each entry in the array is a separate Admin type. If no Admins are available, the resulting array will be empty. This request should never return an error.
path Parameters
org_domain required | string Example: shark-academy The domain is a string value in lowercase with dashes, generated from the organization’s name. |
query Parameters
page | integer Example: page=1 Precise the page of your listing. |
per_page | integer Example: per_page=2 Precise the size of the pages of the pagination of the list. |
Responses
Request samples
- cURL
curl 'https://${cryptr_service_url}/api/v2/org/${org_domain}/admins' \ -d page=${page} -d per_page=${per_page}
Response samples
- 200
- 401
{- "__type__": "List",
- "data": [
- {
- "accepted_invitation_at": null,
- "color": "red-500",
- "declined_to_be_in_charge_at": null,
- "email": "it_sso_person@sso.client.com",
- "id": "64a13b92-e635-4931-a96f-5312fe3ba418",
- "inserted_at": "2023-06-09T16:22:44",
- "invited_at": "2023-06-09T16:22:44",
- "last_login_at": null,
- "organization": {
- "__type__": "Organization",
- "allowed_email_domains": [
- "barker.co"
], - "domain": "barker-inc",
- "environments": [
- {
- "name": "production",
- "status": "down"
}, - {
- "name": "sandbox",
- "status": "up"
}
], - "inserted_at": "2023-06-08T12:12:28",
- "name": "Barker",
- "status": {
- "errors": [ ],
- "estimated_time_to_complete_in_seconds": null,
- "progress_in_percentage": null,
- "state": "pending"
}, - "updated_at": "2023-06-08T12:37:59"
}, - "updated_at": "2023-06-09T16:22:44"
}
], - "pagination": {
- "current_page": 1,
- "current_pages": [
- 1,
- 2,
- 3,
- "...",
- 6
], - "next_page": 2,
- "per_page": 2,
- "prev_page": null,
- "total_pages": 6
}, - "total": 11
}
Retrieve an Admin
path Parameters
org_domain required | string Example: loirama The domain is a string value in lowercase with dashes, generated from the organization’s name. |
email required | string Example: it_sso_person@sso.client.com The email of your Admin |
Responses
Request samples
- cURL
curl '${cryptr_service_url}/api/v2/org/${org_domain}/admins/${email}'
Response samples
- 200
- 401
- 404
{- "accepted_invitation_at": null,
- "color": "red-500",
- "declined_to_be_in_charge_at": null,
- "email": "it_sso_person@sso.client.com",
- "id": "64a13b92-e635-4931-a96f-5312fe3ba418",
- "inserted_at": "2023-06-09T16:22:44",
- "invited_at": "2023-06-09T16:22:44",
- "last_login_at": null,
- "organization": {
- "__type__": "Organization",
- "allowed_email_domains": [
- "barker.co"
], - "domain": "barker-inc",
- "environments": [
- {
- "name": "production",
- "status": "down"
}, - {
- "name": "sandbox",
- "status": "up"
}
], - "inserted_at": "2023-06-08T12:12:28",
- "name": "Barker",
- "status": {
- "errors": [ ],
- "estimated_time_to_complete_in_seconds": null,
- "progress_in_percentage": null,
- "state": "pending"
}, - "updated_at": "2023-06-08T12:37:59"
}, - "updated_at": "2023-06-09T16:22:44"
}
The Webhook in Cryptr allows you to stay informed about activities happening on your App or Directory Sync.
For example, if a user is created, the change will be automatically reflected, and the details will be sent to your target URL. Several actions are supported, including updating, deleting, or creating resources.
The Webhook type
You can create one or more Webhooks for each organization domain and environment pair. For example, if your organization's domain is "misapret" and you have a "sandbox" environment, you can create a Webhook for "misapret/sandbox". However, if you also have a "production" environment, you will only receive information from your "sandbox" environment. To receive information from your "production" environment as well, you will need to create an additional webhook.
__environment__ | string The environment in which the user is stored, either sandbox (for the test environment) or production. |
__type__ | string The |
active | boolean Indicates whether the webhook is active. |
event_codes | Array of enum Identifiers used to specify types of events within a webhook. See the full list of events |
id | string A unique string that identifies a specific webhook. |
inserted_at | string <date-time> Insertion datetime |
name | string The name of your webhook, which serves as a label to help you understand its purpose. |
signature_key | string This value ensures the integrity of the response and authenticates the author. |
target_url | string Refers to the specific URL where you want to receive event information. |
updated_at | string <date-time> Updated datetime |
{- "__environment__": "sandbox",
- "__type__": "Webhook",
- "active": true,
- "event_codes": [
- "dir_sync.user.provision.success"
], - "id": "webhook_2RCVpicx8L7cFwhrz2gHjnsCLKQ",
- "inserted_at": "2023-06-14T14:50:34",
- "name": "My Webhook Name",
- "signature_key": "Rjyhf8JcIfPtUhagKRKsu2Delq0JR3z6huEuJJLUwTaK8U380sA1tEgY_4aJYaRNbh_s2-u5_IWbrWQBV_DiDWAX1XNEV6DHDV8cvYGo00PkA32yWrwgEEG9ajbQ-IIT",
- "updated_at": "2023-06-14T14:50:34"
}
Create a Webhook
Creates a new Webhook for your organization. When you create a Webhook, you will receive the associated signature key.
Note: When you create a Webhook, its storage location is determined by the environment of your API key. For example, a Webhook is created in the sandbox environment only if the corresponding resource is stored in the sandbox. You cannot create a Webhook in the Production environment with this API key; you need an API key dedicated to that environment.
query Parameters
name required | string Example: name=My Webhook Name The name of your webhook you can set it to anything you want |
event_codes[] required | Array of strings Example: event_codes[]=dir_sync.user.provision.success Identifiers used to specify types of events within a webhook. See the full list of events |
target_url required | string Example: target_url=http://webhook.site Refers to the specific URL where you want to receive event information. |
Responses
Request samples
- cURL
curl -X POST '${cryptr_service_url}/api/v2/webhooks' \ -d 'name=New Webhook' \ -d 'target_url=https://webhook.site' \ -d 'event_codes=dir_sync.user.provision.success'
Response samples
- 201
- 422
{- "__environment__": "sandbox",
- "__type__": "Webhook",
- "active": true,
- "event_codes": [
- "dir_sync.user.provision.success"
], - "id": "webhook_2RCVpicx8L7cFwhrz2gHjnsCLKQ",
- "inserted_at": "2023-06-14T14:50:34",
- "name": "My Webhook Name",
- "signature_key": "Rjyhf8JcIfPtUhagKRKsu2Delq0JR3z6huEuJJLUwTaK8U380sA1tEgY_4aJYaRNbh_s2-u5_IWbrWQBV_DiDWAX1XNEV6DHDV8cvYGo00PkA32yWrwgEEG9ajbQ-IIT",
- "updated_at": "2023-06-14T14:50:34"
}
Delete a Webhook
Use the request below when you want to delete a Webhook.
RETURNS
The deleted Webhook
path Parameters
id required | string Example: webhook_2R6eHbyzOezQhb3gkhAlqclt6oT A unique string that identifies a specific webhook. |
Responses
Request samples
- cURL
curl -X DELETE '${cryptr_service_url}/api/v2/webhooks/${id}'
Response samples
- 200
- 404
{- "deleted": true,
- "resource": {
- "__environment__": "sandbox",
- "__type__": "Webhook",
- "active": true,
- "event_codes": [
- "dir_sync.user.provision.success"
], - "id": "webhook_2RCVpicx8L7cFwhrz2gHjnsCLKQ",
- "inserted_at": "2023-06-14T14:50:34",
- "name": "My Webhook Name",
- "signature_key": "Rjyhf8JcIfPtUhagKRKsu2Delq0JR3z6huEuJJLUwTaK8U380sA1tEgY_4aJYaRNbh_s2-u5_IWbrWQBV_DiDWAX1XNEV6DHDV8cvYGo00PkA32yWrwgEEG9ajbQ-IIT",
- "updated_at": "2023-06-14T14:50:34"
}
}
List all Webhooks
Retrieve all your organization’s Webhooks using pagination or not.
Note: When you fetch the Webhooks, the environment of your API key determines where your Webhooks are stored. For example, your Webhooks in the sandbox are fetched only if the resources are stored in the sandbox. You can’t fetch Webhooks from the Production environment with this API key; you need an API key dedicated to this environment.
RETURNS
Returns a list of Webhooks for a valid organization/environment pair. If no Webhooks exist, an empty list is displayed.
query Parameters
page | integer Example: page=1 Precise the page of your listing. |
per_page | integer Example: per_page=8 Precise the size of the pages of the pagination of the list. |
Responses
Request samples
- cURL
curl '${cryptr_service_url}/api/v2/webhooks' \ -d "page=${page}" \ -d "per_page=${per_page}" \
Response samples
- 200
{- "__type__": "List",
- "data": [
- {
- "__environment__": "sandbox",
- "__type__": "Webhook",
- "active": true,
- "event_codes": [
- "dir_sync.user.provision.success"
], - "id": "webhook_2REPA0hJihspyjNTrfeLZYrOYS2",
- "inserted_at": "2023-06-15T06:55:19",
- "name": "My Webhook Name",
- "signature_key": "VmL3Gsslj_IWyM4KYmpBYF1URbyHWdOMrogPjD0-yN1nrRPIyPlfr3U-Jv-jonQwRgYkJ6io4a-P_tycQ1ci9ZIfCzACvVNQQYBQzULQ9RPrO7XhMuYGK07XrqHWU2jS",
- "updated_at": "2023-06-15T06:55:19"
}, - {
- "__environment__": "sandbox",
- "__type__": "Webhook",
- "active": true,
- "event_codes": [
- "dir_sync.activate.success",
- "dir_sync.deactivate.success"
], - "id": "webhook_2RCVuHlyhadTW8IJfrbjU2KW4G1",
- "inserted_at": "2023-06-14T14:51:10",
- "name": "Super Webhook",
- "signature_key": "4qmmFSOoZQLhlhV50bkNgp0SZt9EpNApUAToYLlFpgRYI-eJ7XHb9KDTuVtEhf7VKSb-0mySqUNRxo54IZ7hj-UxNP6RboQt4sUh0A-Rnt8rD6ERhDRG2Tzhl5V-q1h7",
- "updated_at": "2023-06-14T14:51:10"
}, - {
- "__environment__": "sandbox",
- "__type__": "Webhook",
- "active": true,
- "event_codes": [
- "sso_saml.user.jit_provision.success",
- "sso_saml.user.update.success"
], - "id": "webhook_2RCTwiofROfxs3NTkx5BpsmwTUg",
- "inserted_at": "2023-06-14T14:35:03",
- "name": "Super Webhook",
- "signature_key": "sTyVwG3b3A_01bhzQolwtxiDce1DAwm_lz_6BBLBouxvjCZBykJmVa2pDmcOkAjkgJkrXvM9lhVo2bI9cctUqXN7QMWkfcU6LgqZKgUMJ2onA-ccA2CjJw_a2zIXGtqU",
- "updated_at": "2023-06-14T14:35:03"
}
], - "pagination": {
- "current_page": 1,
- "current_pages": [
- 1,
- 2,
- 3,
- "...",
- 6
], - "next_page": 2,
- "per_page": 3,
- "prev_page": null,
- "total_pages": 6
}, - "total": 16
}
Retrieve a Webhook
Retrieve Webhook information for your organization using its identifier.
Note: When you fetch a Webhook, the environment of your API key determines where your Webhook is stored. For example, your Webhook in the sandbox is fetched only if this resource is stored in the sandbox. You can't fetch a Webhook from the Production environment with this API key; you need an API key dedicated to that environment.
RETURNS
Returns the Webhook for a valid organization/environment pair. If it’s for a deleted Webhook, a Not Found response is displayed.
path Parameters
id required | string Example: webhook_2R6eHbyzOezQhb3gkhAlqclt6oT A unique string that identifies a specific webhook. |
Responses
Request samples
- cURL
curl '${cryptr_service_url}/api/v2/webhooks/${id}'
Response samples
- 200
- 404
{- "__environment__": "sandbox",
- "__type__": "Webhook",
- "active": true,
- "event_codes": [
- "dir_sync.user.provision.success"
], - "id": "webhook_2RCVpicx8L7cFwhrz2gHjnsCLKQ",
- "inserted_at": "2023-06-14T14:50:34",
- "name": "My Webhook Name",
- "signature_key": "Rjyhf8JcIfPtUhagKRKsu2Delq0JR3z6huEuJJLUwTaK8U380sA1tEgY_4aJYaRNbh_s2-u5_IWbrWQBV_DiDWAX1XNEV6DHDV8cvYGo00PkA32yWrwgEEG9ajbQ-IIT",
- "updated_at": "2023-06-14T14:50:34"
}
Update a Webhook
Update an existing Webhook for your Organization. You can only update the event_codes and the target_url. For example, if your previous target_url has changed since the webhook was created.
RETURNS
Returns the updated Webhook for a valid organization/environment pair. If not found, a 404 Not Found response is displayed.
path Parameters
id required | string Example: webhook_2R6eHbyzOezQhb3gkhAlqclt6oT A unique string that identifies a specific webhook. |
query Parameters
event_codes[] | Array of strings Example: event_codes[]=sso_saml.user.jit_provision.success Identifiers used to specify types of events within a webhook. See the full list of events |
target_url | string Example: target_url=http://webhook.site Refers to the specific URL where you want to receive event information. |
name | string Example: name=My Webhook Name The name of your webhook you can set it to anything you want. |
Responses
Request samples
- cURL
curl -X PUT '${cryptr_service_url}/api/v2/webhooks/${id}' \ -d "event_codes[]=sso_saml.user.jit_provision.success" \ -d "target_url=http://webhook.site" \ -d "name=My Webhook Name"
Response samples
- 200
- 404
{- "__environment__": "sandbox",
- "__type__": "Webhook",
- "active": true,
- "event_codes": [
- "dir_sync.user.provision.success"
], - "id": "webhook_2RCVpicx8L7cFwhrz2gHjnsCLKQ",
- "inserted_at": "2023-06-14T14:50:34",
- "name": "My Webhook Name",
- "signature_key": "Rjyhf8JcIfPtUhagKRKsu2Delq0JR3z6huEuJJLUwTaK8U380sA1tEgY_4aJYaRNbh_s2-u5_IWbrWQBV_DiDWAX1XNEV6DHDV8cvYGo00PkA32yWrwgEEG9ajbQ-IIT",
- "updated_at": "2023-06-14T14:50:34"
}
The Webhook Event type
__type__ | string The |
object (Event) The payload of the Webhook Event that was sent to you. | |
attempt | integer The number of attempts that have been made. |
attempted_at | string The last date on which an attempt was made. |
cancelled_at | string The date on which the event sending was cancelled. |
completed_at | string The date on which the event sending was successful. |
discarded_at | string The date when the event sending was discarded. |
id | integer Immutable identifier. |
inserted_at | string <date-time> Insertion datetime |
max_attempts | integer The maximum number of attempts to send the event. Maximum is 5 unless you use the retry-after option. |
scheduled_at | string The date on which the event sending was scheduled. |
state | string The states of the event sending. The different states are:
|
{- "__type__": "WebhookEvent",
- "args": {
- "__domain__": "shark-academy",
- "__environment__": "sandbox",
- "__type__": "Event",
- "code": "dir_sync.activate.success",
- "data": {
- "__type__": "DirectorySyncEvent",
- "directory_sync_id": "f71c2961-ebbd-4364-a6bd-e585614b9458",
- "provider": "okta"
}, - "issued_at": "2023-06-13T08:57:59.617402Z",
- "webhook_id": "webhook_2QbwnDHL6z4TsohFvzOoE74NBvJ"
}, - "attempt": 1,
- "attempted_at": "2023-06-13T08:57:59.632125Z",
- "cancelled_at": null,
- "completed_at": "2023-06-13T08:57:59.761073Z",
- "discarded_at": null,
- "id": 80,
- "inserted_at": "2023-06-13T08:57:59.621406Z",
- "max_attempts": 5,
- "scheduled_at": "2023-06-13T08:57:59.621406Z",
- "state": "completed"
}
Cancel Webhook Event
Returns the canceled job when we have taken into account your request for a cancel. If not, you will receive an error message.
Note: When a cancel request is successful, the status of your Webhook Event should change to 'canceled.'
RETURNS
The canceled job. If the Webhook Events you requested to cancel don’t exist or if an error occurred, an error message will be sent.
path Parameters
id required | int Example: 42 Unique identifier assigned to a webhook event. |
Responses
Request samples
- cURL
curl -X POST '${cryptr_service_url}/api/v2/webhook-events/${id}/cancel'
Response samples
- 200
- 404
{- "__type__": "WebhookEvent",
- "args": {
- "__domain__": "shark-academy",
- "__environment__": "sandbox",
- "__type__": "Event",
- "code": "dir_sync.activate.success",
- "data": {
- "__domain__": "shark-academy",
- "__type__": "DirectorySyncEvent",
- "change": "create",
- "directory_sync_id": "14630346-0cd3-4cc6-8f88-9ca27e3f60fe",
- "provider": "okta",
- "resource": {
- "changes": {
- "new_values": {
- "__domain__": "shark-academy",
- "__environment__": "sandbox",
- "__type__": "User",
- "address": {
- "country": "BE",
- "formatted": "3 Heathcote Mall\n44843 New Fabiola, Belgium",
- "locality": "New Fabiola",
- "postal_code": "44843",
- "region": "Florida",
- "street_address": "3 Heathcote Mall"
}, - "email": "madilyn.blanda@gutmann.com",
- "email_verified": false,
- "id": "bcee32ef-475a-4ada-8b58-a0cc516a3b7d",
- "inserted_at": "2023-06-13T13:14:22",
- "meta_data": [ ],
- "phone_number": null,
- "phone_number_verified": false,
- "profile": {
- "birthdate": "1970-08-18",
- "family_name": "Blanchet",
- "gender": null,
- "given_name": "Estelle",
- "locale": "en_US",
- "nickname": "Ginette",
- "preferred_username": "kiley.gleason",
- "zoneinfo": "America/Chicago"
}, - "updated_at": "2023-06-13T13:14:22"
}, - "previous_values": null
}, - "id": "user_c8fcaf9d-fcbf-4b6f-a37f-70ec75d1a144",
- "type": "User"
}
}, - "issued_at": "2023-06-13T09:03:18.750478Z",
- "webhook_id": "webhook_2QbwnDHL6z4TsohFvzOoE74NBvJ"
}, - "attempt": 1,
- "attempted_at": "2023-06-13T09:03:18.819155Z",
- "cancelled_at": "2023-06-15T15:17:33.666466Z",
- "completed_at": "2023-06-13T09:03:18.920373Z",
- "discarded_at": null,
- "id": 81,
- "inserted_at": "2023-06-13T09:03:18.754610Z",
- "max_attempts": 5,
- "scheduled_at": "2023-06-13T09:03:18.754610Z",
- "state": "cancelled"
}
List Webhook Events
The Webhook Events are returned sorted by issued date, with the most recent issued events appearing first.
Note: Webhook Events have a 24-hour lifespan. After this period, they are deleted unless their state is
available
,scheduled
,executing
orretryable
.
RETURNS
Returns a list of your Webhook Events.
query Parameters
page | integer Example: page=1 Precise the page of your listing. |
per_page | integer Example: per_page=8 Precise the size of the pages of the pagination of the list. |
Responses
Request samples
- cURL
curl '${cryptr_service_url}/api/v2/webhook-events' -d "page=${page}" \ -d "per_page=${per_page}" \
Response samples
- 200
{- "__type__": "List",
- "data": [
- {
- "__type__": "WebhookEvent",
- "args": {
- "__domain__": "follow-the-market",
- "__environment__": "production",
- "__type__": "Event",
- "code": "dir_sync.user.create.success",
- "data": {
- "__domain__": "shark-academy",
- "__type__": "DirectorySyncEvent",
- "change": "create",
- "directory_sync_id": "14630346-0cd3-4cc6-8f88-9ca27e3f60fe",
- "provider": "okta",
- "resource": {
- "changes": {
- "new_values": {
- "__domain__": "shark-academy",
- "__environment__": "sandbox",
- "__type__": "User",
- "address": {
- "country": "BE",
- "formatted": "3 Heathcote Mall\n44843 New Fabiola, Belgium",
- "locality": "New Fabiola",
- "postal_code": "44843",
- "region": "Florida",
- "street_address": "3 Heathcote Mall"
}, - "email": "madilyn.blanda@gutmann.com",
- "email_verified": false,
- "id": "bcee32ef-475a-4ada-8b58-a0cc516a3b7d",
- "inserted_at": "2023-06-13T13:14:22",
- "meta_data": [ ],
- "phone_number": null,
- "phone_number_verified": false,
- "profile": {
- "birthdate": "1970-08-18",
- "family_name": "Blanchet",
- "gender": null,
- "given_name": "Estelle",
- "locale": "en_US",
- "nickname": "Ginette",
- "preferred_username": "kiley.gleason",
- "zoneinfo": "America/Chicago"
}, - "updated_at": "2023-06-13T13:14:22"
}, - "previous_values": null
}, - "id": "user_c8fcaf9d-fcbf-4b6f-a37f-70ec75d1a144",
- "type": "User"
}
}, - "issued_at": "~U[2023-05-17 10:38:13.339032Z]",
- "webhook_id": "webhook_id"
}, - "attempt": 1,
- "attempted_at": "~U[2023-05-17 10:38:13.447032Z]",
- "attempted_by": null,
- "cancelled_at": null,
- "completed_at": "~U[2023-05-17 10:38:13.449032Z]",
- "discarded_at": null,
- "inserted_at": "~U[2023-05-17 10:38:13.439032Z]",
- "max_attempts": 5,
- "scheduled_at": "~U[2023-05-17 10:38:17.000000Z]",
- "state": "scheduled"
}
], - "pagination": {
- "current_page": 1,
- "current_pages": [
- 1
], - "next_page": null,
- "per_page": 10,
- "prev_page": null,
- "total_pages": 1
}, - "total": 1
}
Retry Webhook Event
Returns the job for which you requested a retry once we have considered your request. Otherwise, you will receive an error message.
Note: When a retry request is successful the status of your Webhook Event should change to 'available'.
RETURNS
The job to be retried. If the Webhook Events you requested for retry do not exist or if an error occurs, an error message will be sent.
path Parameters
id required | int Example: 42 Unique identifier assigned to a webhook event. |
Responses
Request samples
- cURL
curl -X POST '${cryptr_service_url}/api/v2/webhook-events/${id}/retry'
Response samples
- 200
- 404
{- "__type__": "WebhookEvent",
- "args": {
- "__domain__": "shark-academy",
- "__environment__": "sandbox",
- "__type__": "Event",
- "code": "dir_sync.activate.success",
- "data": {
- "__domain__": "shark-academy",
- "__type__": "DirectorySyncEvent",
- "change": "create",
- "directory_sync_id": "14630346-0cd3-4cc6-8f88-9ca27e3f60fe",
- "provider": "okta",
- "resource": {
- "changes": {
- "new_values": {
- "__domain__": "shark-academy",
- "__environment__": "sandbox",
- "__type__": "User",
- "address": {
- "country": "BE",
- "formatted": "3 Heathcote Mall\n44843 New Fabiola, Belgium",
- "locality": "New Fabiola",
- "postal_code": "44843",
- "region": "Florida",
- "street_address": "3 Heathcote Mall"
}, - "email": "madilyn.blanda@gutmann.com",
- "email_verified": false,
- "id": "bcee32ef-475a-4ada-8b58-a0cc516a3b7d",
- "inserted_at": "2023-06-13T13:14:22",
- "meta_data": [ ],
- "phone_number": null,
- "phone_number_verified": false,
- "profile": {
- "birthdate": "1970-08-18",
- "family_name": "Blanchet",
- "gender": null,
- "given_name": "Estelle",
- "locale": "en_US",
- "nickname": "Ginette",
- "preferred_username": "kiley.gleason",
- "zoneinfo": "America/Chicago"
}, - "updated_at": "2023-06-13T13:14:22"
}, - "previous_values": null
}, - "id": "user_c8fcaf9d-fcbf-4b6f-a37f-70ec75d1a144",
- "type": "User"
}
}, - "issued_at": "2023-06-13T09:03:18.750478Z",
- "webhook_id": "webhook_2QbwnDHL6z4TsohFvzOoE74NBvJ"
}, - "attempt": 1,
- "attempted_at": "2023-06-13T09:03:18.819155Z",
- "cancelled_at": null,
- "completed_at": "2023-06-13T09:03:18.920373Z",
- "discarded_at": null,
- "id": 81,
- "inserted_at": "2023-06-13T09:03:18.754610Z",
- "max_attempts": 5,
- "scheduled_at": "2023-06-13T09:03:18.754610Z",
- "state": "available"
}
Test Webhook Event
Returns the payload of the event you should receive for a particular event_code
if your webhook is well configured.
Note: Not all event codes are available for testing.
RETURNS
The preview of the event you should receive. If no webhook is linked to this event_code
, the preview will be nil, along with two lists of triggered and non-triggered webhooks.
query Parameters
event_code required | string Example: event_code=dir_sync.user.update.success The event code for which you want to simulate a fake event. |
Responses
Request samples
- cURL
curl -X POST '${cryptr_service_url}/api/v2/webhook-events/trigger-test' --header 'Authorization: Bearer your_api_key_generated_token' \ --header 'Content-Type: application/json' \ -d event_code="dir_sync.user.update.success"
Response samples
- 200
{- "__type__": "WebhookEventTest",
- "preview": {
- "__domain__": "shark-academy",
- "__environment__": "sandbox",
- "__type__": "Event",
- "code": "dir_sync.user.provision.success",
- "data": {
- "__domain__": "shark-academy",
- "__type__": "DirectorySyncEvent",
- "change": "create",
- "directory_sync_id": "70b4ee66-4d2d-45ed-b351-292727ba0050",
- "provider": "okta",
- "resource": {
- "changes": {
- "new_values": {
- "__domain__": "shark-academy",
- "__environment__": "sandbox",
- "__type__": "User",
- "address": {
- "country": "FR",
- "formatted": "0465 Lelah Fields\n78361 Kshlerin, France",
- "locality": "Kshlerin",
- "postal_code": "78361",
- "region": "New Hampshire",
- "street_address": "0465 Lelah Fields"
}, - "email": "reymundo2060@spencer.biz",
- "email_verified": false,
- "id": "7862c0ce-2c3d-4045-95f1-d1fb942b71a0",
- "inserted_at": "2023-06-13T13:14:22",
- "meta_data": [ ],
- "phone_number": null,
- "phone_number_verified": false,
- "profile": {
- "birthdate": "1929-07-20",
- "family_name": "Vernier",
- "gender": null,
- "given_name": "Pierre",
- "locale": "fr_FR",
- "nickname": "Victor",
- "preferred_username": "sienna2028",
- "zoneinfo": "America/Chicago"
}, - "updated_at": "2023-06-13T13:14:22"
}, - "previous_values": null
}, - "id": "user_2771734b-4d4a-46c5-bd08-56ef6a3089a0",
- "type": "User"
}
}, - "issued_at": "2023-06-27T09:37:03.745212Z",
- "webhook_id": "webhook_2RmcDyFCS3jOwaGNh0NufCrpbBD"
}, - "triggered_webhooks": [
- {
- "__environment__": "sandbox",
- "__type__": "Webhook",
- "active": true,
- "event_codes": [
- "dir_sync.user.provision.success"
], - "id": "webhook_2RmcDyFCS3jOwaGNh0NufCrpbBD",
- "inserted_at": "2023-06-27T09:36:20",
- "name": "My Webhook Name",
- "signature_key": "6H0dAygazkUpiJJe_oMajpNVuFz6QvkSVHYvYzLCArqiOFWXTwaVJFFBOk1xBOg0vX81TKTtW4Md48KJ_ah3SQRUt0W8J1a_ayXTA4tX-srnMDPRzzkNablSms7pVqp4",
- "updated_at": "2023-06-27T09:36:20"
}
], - "untriggered_webhooks": [ ]
}
After a successful end-user authentication, they will be redirected to one of its allowed environment Redirect URIs.
The Redirect URI type
__environment__ | string The environment in which the user is stored, either sandbox (for the test environment) or production. |
__type__ | string Data type |
default | boolean Default: false If it’s the default for its environment, it cannot be deleted if |
id | uuid < |