Aller au contenu principal
API docs by Redocly

API reference (2.0)

Complete reference documentation for the Cryptr API. Includes code snippets and examples.

🧑‍🤝‍🧑 Organizations

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 __type__ is a string that lets you differentiate data types.

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 domain field. 'Awesome company' will become 'awesome-company'.

object (Status)

This status object tracks the state of an organization creation, using fields like state and errors to indicate the progress of the operation.

timezone
string

Your organization’s preferred timezone

updated_at
string <date-time>

Update timestamp

{
  • "__type__": "Organization",
  • "allowed_email_domains": [
    ],
  • "color": "red-500",
  • "domain": "weeklymotion",
  • "environments": [
    ],
  • "icon_logo_url": "https://...",
  • "inline_logo_url": "https://...",
  • "inserted_at": "2023-05-10T06:16:35",
  • "locale": "en-US",
  • "name": "Weeklymotion",
  • "status": {
    },
  • "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 domain field. 'Awesome company' will become 'awesome-company'.

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 -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

Content type
application/json
{
  • "__type__": "Organization",
  • "allowed_email_domains": [
    ],
  • "color": "red-500",
  • "domain": "weeklymotion",
  • "environments": [
    ],
  • "icon_logo_url": "https://...",
  • "inline_logo_url": "https://...",
  • "inserted_at": "2023-05-04T07:16:56",
  • "locale": "en-US",
  • "name": "Weeklymotion",
  • "status": {
    },
  • "timezone": "Coordinated Universal Time (UTC)",
  • "updated_at": "2023-05-04T07:16:56"
}

Delete an Organization

Delete an Organization with a domain.

RETURNS

Returns the deleted 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 -X DELETE
  '${cryptr_service_url}/api/v2/organizations/${org_domain}'

Response samples

Content type
application/json
{
  • "deleted": true,
  • "resource": {
    }
}

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 '${cryptr_service_url}/api/v2/organizations' \
  -d "page=${page}" \
  -d "per_page=${per_page}" \
  -d "q[environments_status_in][]=up"

Response samples

Content type
application/json
{
  • "__type__": "List",
  • "data": [
    ],
  • "pagination": {
    },
  • "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 '${cryptr_service_url}/api/v2/organizations/${org_domain}'

Response samples

Content type
application/json
{
  • "__type__": "Organization",
  • "allowed_email_domains": [
    ],
  • "color": "red-500",
  • "domain": "weeklymotion",
  • "environments": [
    ],
  • "icon_logo_url": "https://...",
  • "inline_logo_url": "https://...",
  • "inserted_at": "2023-05-04T07:16:56",
  • "locale": "en-US",
  • "name": "Weeklymotion",
  • "status": {
    },
  • "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 -X PUT
  '${cryptr_service_url}/api/v2/organizations/${org_domain}'

Response samples

Content type
application/json
{
  • "__type__": "Organization",
  • "allowed_email_domains": [
    ],
  • "color": "red-500",
  • "domain": "weeklymotion",
  • "environments": [
    ],
  • "icon_logo_url": "https://...",
  • "inline_logo_url": "https://...",
  • "inserted_at": "2023-05-04T07:16:56",
  • "locale": "en-US",
  • "name": "Weeklymotion",
  • "status": {
    },
  • "timezone": "Coordinated Universal Time (UTC)",
  • "updated_at": "2023-05-04T07:16:56"
}

👩‍💻 Users

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 Address, as defined here.

email
string <email>

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": {
    },
  • "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": {
    },
  • "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",
  • "picture": "https://www.cryptr.co",
  • "preferred_username": null,
  • "website": "http://www.example.com",
  • "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 -X PUT '${cryptr_service_url}/api/v2/org/:org_domain/users/:user_id/add-metadata' \
  -d key='uid' \
  -d value='2fa42937'

Response samples

Content type
application/json
{
  • "__domain__": "loirama",
  • "__environment__": "sandbox",
  • "__type__": "User",
  • "active": true,
  • "address": {
    },
  • "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": {
    },
  • "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
object (Address)
Example: country=FR&formatted=165 avenue de Bretagne 59000 Lille, France&locality=Lille&postal_code=59000&region=Nord&street_address=165 avenue de Bretagne

User’s postal address. The value of the address member is an Address type defined here.

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
string
Example: phone_number=+33123456789

User telephone number in E.164 format.

object (Profile)
Example: birthdate=1992-03-10&family_name=Bloggs&gender=female&given_name=Lyla&locale=fr&nickname=lylaB&picture=https://www.cryptr.co&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 -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]="https://www.cryptr.co"'
  --form 'profile[website]="http://www.example.com"'
  --form 'profile[gender]="female"'
  --form 'profile[zoneinfo]="France/Lille"'
  --form 'profile[locale]="fr"'

Response samples

Content type
application/json
{
  • "__domain__": "loirama",
  • "__environment__": "sandbox",
  • "__type__": "User",
  • "active": true,
  • "address": {
    },
  • "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": {
    },
  • "updated_at": "2023-05-10T13:50:35"
}

Delete a User By ID

Delete an existing user.

RETURNS

Returns a deleted User from an Organization.

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 -X DELETE '${cryptr_service_url}/api/v2/org/${org_domain}/users/${user_id}'

Response samples

Content type
application/json
{
  • "deleted": true,
  • "resource": {
    }
}

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 "${cryptr_service_url}/api/v2/org/${org_domain}/users" \
  -d page=${page}
  -d per_page=${per_page}

Response samples

Content type
application/json
{
  • "__type__": "List",
  • "data": [
    ],
  • "pagination": {
    },
  • "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 -X PUT '${cryptr_service_url}/api/v2/org/:org_domain/users/:user_id/remove-metadata' \
  -d key='uid'

Response samples

Content type
application/json
{
  • "__domain__": "loirama",
  • "__environment__": "sandbox",
  • "__type__": "User",
  • "address": {
    },
  • "email": "lyla@loirama.co",
  • "email_verified": false,
  • "id": "d6a46443-c7bc-4259-aa5d-ce51cc548b57",
  • "inserted_at": "2023-05-10T13:50:35",
  • "meta_data": [
    ],
  • "phone_number": "+33 1 23 45 67 89",
  • "phone_number_verified": false,
  • "profile": {
    },
  • "updated_at": "2023-05-10T13:50:35"
}

Retrieve a User By Email or ID

Fetch a User by their email or id.

RETURNS

Returns a User for a valid email or identifier. If the User has been deleted, a subset of their information is returned, including a deleted property set to true.

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 '${cryptr_service_url}/api/v2/org/${org_domain}/users/${user_id}'

Response samples

Content type
application/json
{
  • "__domain__": "loirama",
  • "__environment__": "sandbox",
  • "__type__": "User",
  • "active": true,
  • "address": {
    },
  • "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": {
    },
  • "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
object (Address)
Example: country=FR&formatted=165 avenue de Bretagne 59000 Lille, France&locality=Lille&postal_code=59000&region=Nord&street_address=165 avenue de Bretagne

User’s postal address. The value of the address member is an Address type defined here.

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
string
Example: phone_number=+33123456789

User telephone number in E.164 format.

given_name
string
Example: given_name=Lyla

The first name is an OpenID Connect profile attribute.

family_name
string
Example: family_name=Bloggs

The last name is an OpenID Connect profile attribute.

nickname
string
Example: nickname=lylaB

It’s an OpenID Connect profile attribute.

picture
string <url>
Example: picture=https://www.cryptr.co

It’s an OpenID Connect profile attribute.

website
string <url>
Example: website=http://www.example.com

It’s an OpenID Connect profile attribute.

gender
string
Enum: "male" "female" null
Example: gender=female

It's an OpenID Connect profile attribute, available options are male, female or null.

zoneinfo
string
Example: zoneinfo=France/Lille

It’s an OpenID Connect profile attribute.

locale
string
Example: locale=fr

It’s an OpenID Connect profile attribute.

Responses

Request samples 


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]="https://www.cryptr.co"'
        --form 'profile[website]="http://www.example.com"'
        --form 'profile[gender]="female"'
        --form 'profile[zoneinfo]="France/Lille"'
        --form 'profile[locale]="fr"'

Response samples

Content type
application/json
{
  • "__domain__": "loirama",
  • "__environment__": "sandbox",
  • "__type__": "User",
  • "active": true,
  • "address": {
    },
  • "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": {
    },
  • "updated_at": "2023-05-10T13:50:35"
}

🔄 Directory Syncs

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 __type__ is a string that lets you differentiate data types.

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., dir_sync.okta, dir_sync.ping_one, dir_sync.azure_ad.

updated_at
string <date-time>

Update timestamp

{
  • "__domain__": "barker-inc",
  • "__environment__": "sandbox",
  • "__type__": "DirectorySync",
  • "active": true,
  • "auth_secret_token": {
    },
  • "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 -X POST '${cryptr_service_url}/api/v2/org/${org_domain}/directory-sync'

Response samples

Content type
application/json
{
  • "__domain__": "barker-inc",
  • "__environment__": "sandbox",
  • "__type__": "DirectorySync",
  • "active": true,
  • "auth_secret_token": {
    },
  • "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 -X '${cryptr_service_url}/api/v2/org/${org_domain}/directory-sync'

Response samples

Content type
application/json
{
  • "__domain__": "barker-inc",
  • "__environment__": "sandbox",
  • "__type__": "DirectorySync",
  • "active": true,
  • "auth_secret_token": {
    },
  • "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 -X PUT '${cryptr_service_url}/api/v2/org/${org_domain}/directory-sync'

Response samples

Content type
application/json
{
  • "__domain__": "barker-inc",
  • "__environment__": "sandbox",
  • "__type__": "DirectorySync",
  • "active": true,
  • "auth_secret_token": {
    },
  • "id": "32dad740-142e-4af3-ac69-de5f36915d80",
  • "inserted_at": "2023-06-15T09:23:55",
  • "provider_type": null,
  • "updated_at": "2023-06-15T09:23:55"
}

🔌 SSO

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
  • Google
  • 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 __type__ is a string that lets you differentiate data types.

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: only_registered_users (users already registered), provision_new_users (automatic account creation) and unregistered_users_allowed (no provisioning action).

{
  • "__type__": "SsoConnection",
  • "active": true,
  • "id": "barker_inc_S6f5ndf8mZqfoBKoxEotMV",
  • "inserted_at": "2023-06-08T13:47:41",
  • "number_users_provisioning_limit": 99,
  • "organization": {
    },
  • "provider_type": "saml.azure_ad",
  • "saml_config": {},
  • "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 __type__ is a string that lets you differentiate data types.

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,
  • "redirect_uri": "https://b-oreal.com/welcome-back-user",
  • "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 user_email or org_domain must be provided, but not both at the same time, to create an SSO challenge.

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 org_domain or user_email must be provided, but not both at the same time, to create an SSO challenge.

Responses

Request samples 


curl -X POST '${cryptr_service_url}/api/v2/sso-saml-challenge' \
  -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

Content type
application/json
{
  • "__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,
  • "redirect_uri": "https://loirama.com/welcome-back-user",
  • "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 value.

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 users_access_policy key determines how users are managed when they log in for the first time via SSO.

Possible values for this key are:

  • only_registered_users: the user must already be registered in the organization. This means that the user must have been manually added to the user database before being able to log in via SSO. If the user is not registered, they will not be able to log in.
  • provision_new_users: When the user attempts to log in for the first time, the system will automatically create a user for them.
  • unregistered_users_allowed: No provisioning action is taken when the user logs in for the first time. This option is useful when it is not necessary to check the user individually, but only the organization.
active
boolean
Default: true

If you want to create it but not activate it for now

Responses

Request samples 


curl -X POST '${cryptr_service_url}/api/v2/org/${org_domain}/sso-connection'

Response samples

Content type
application/json
{
  • "__type__": "SsoConnection",
  • "active": true,
  • "id": "barker_inc_S6f5ndf8mZqfoBKoxEotMV",
  • "inserted_at": "2023-06-08T13:47:41",
  • "number_users_provisioning_limit": 99,
  • "organization": {
    },
  • "provider_type": "saml.azure_ad",
  • "saml_config": {},
  • "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
integer
Example: page=1

Specify the page of your listing.

per_page
integer
Example: per_page=2

Specify the size of the pages for pagination of the list.

Responses

Request samples 

curl '${cryptr_service_url}/api/v2/sso-connections'
          -d page=${page}
          -d per_page=${per_page}

Response samples

Content type
application/json
{
  • "__type__": "List",
  • "data": [
    ],
  • "pagination": {
    },
  • "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 '${cryptr_service_url}/api/v2/org/${org_domain}/sso-connection'

Response samples

Content type
application/json
{
  • "__type__": "SsoConnection",
  • "active": true,
  • "id": "barker_inc_S6f5ndf8mZqfoBKoxEotMV",
  • "inserted_at": "2023-06-08T13:47:41",
  • "number_users_provisioning_limit": 99,
  • "organization": {
    },
  • "provider_type": "saml.azure_ad",
  • "saml_config": {},
  • "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 value.

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 enterprise_connection_onboarding parameter accordingly.

Responses

Request samples 


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

Content type
application/json
{
  • "__type__": "SsoConnection",
  • "active": true,
  • "id": "barker_inc_S6f5ndf8mZqfoBKoxEotMV",
  • "inserted_at": "2023-06-08T13:47:41",
  • "number_users_provisioning_limit": 99,
  • "organization": {
    },
  • "provider_type": "saml.azure_ad",
  • "saml_config": {},
  • "sp_id": "shark_academy_MgF6Z9maZKriEBbLM9KZJj",
  • "updated_at": "2023-06-08T13:47:41",
  • "users_access_policy": "provision_new_users"
}

🔑 Password

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 __type__ is a string that lets you differentiate data types.

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 __type__ is a string that lets you differentiate data types.

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 __type__ is a string that lets you differentiate data types.

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 -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

Content type
application/json
{
  • "__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 org_domain must be provided if you didn't specify an allowed_email_domain when creating your organization, or if several organizations share the same allowed_email_domain.

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 org_domain must be provided if you didn't specify an allowed_email_domain when creating your organization, or if several organizations share the same allowed_email_domain.

plain_text
required
string
Example: plain_text=neripe7845sjHgdeje!

The password of the user as plain text.

Responses

Request samples 


curl -X POST '${cryptr_service_url}/api/v2/password-challenge' \
  -d user_email="lyla@loirama.co" \

Response samples

Content type
application/json
{
  • "__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 -X POST '${cryptr_service_url}/api/v2/org/${org_domain}/password-connection'

Response samples

Content type
application/json
{
  • "__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.

  • True: use the User, if and only if it exists, or create the User
  • False: User MUST exist for challenge creation.

Responses

Request samples 


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

Content type
application/json
{}

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 '${cryptr_service_url}/api/v2/org/${org_domain}/password-connection'

Response samples

Content type
application/json
{
  • "__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 false to disable it, set to true to enable it

Responses

Request samples 

curl -X PUT '${cryptr_service_url}/api/v2/org/${org_domain}/password-connection' \
  -d active=false

Response samples

Content type
application/json
{
  • "__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"
}

🔑 TOTP

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 __type__ is a string that lets you differentiate data types.

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 __type__ is a string that lets you differentiate data types.

email
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 and org_domain must be provided to Create a TOTP Challenge.

user_id
required
uuid
Example: 0d34d179-8a81-49e8-b572-289d0e522691

User immutable identifier

Responses

Request samples 


curl -X POST '${cryptr_service_url}/api/v2/org/${org_domain}/totp-challenge/:user_id'

Response samples

Content type
application/json
{
  • "__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 and org_domain must be provided to create a TOTP enrollment.

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 -X POST '${cryptr_service_url}/api/v2/org/${org_domain}/totp-enrollment/:user_id' \
-d force_enroll='false'

Response samples

Content type
application/json
{
  • "__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 -X GET '${cryptr_service_url}/api/v2/org/${org_domain}/totp-connection

Response samples

Content type
application/json
{
  • "__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 totp_mobile_app and sms.

Responses

Request samples 


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

Content type
application/json
{
  • "__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 and org_domain must be provided to Create a TOTP Challenge.

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 -X PUT '${cryptr_service_url}/api/v2/org/${org_domain}/totp-challenge/validation/:user_id' \
  -d code='478562'

Response samples

Content type
application/json
{
  • "__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 and org_domain must be provided to create a TOTP enrollment.

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 -X PUT '${cryptr_service_url}/api/v2/org/${org_domain}/totp-enrollment/validation/:user_id' \
  -d code='478562'

Response samples

Content type
application/json
{
  • "__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"
}

⚙️ Admin

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.

email
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": {
    },
  • "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 -X POST ${cryptr_service_url}/api/v2/org/${org_domain}/admins

Response samples

Content type
application/json
{
  • "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": {
    },
  • "updated_at": "2023-06-09T16:22:44"
}

Delete an Admin

Delete an Admin by its organization domain and email. The domain is generated from its organization’s name. It’s a unique and immutable value in your Cryptr service.

RETURNS

Returns the deleted Admin for a valid identifier and email.

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 -X DELETE '${cryptr_service_url}/api/v2/org/${org_domain}/admins/${email}'

Response samples

Content type
application/json
{
  • "deleted": true,
  • "resource": {
    }
}

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 'https://${cryptr_service_url}/api/v2/org/${org_domain}/admins' \
  -d page=${page}
  -d per_page=${per_page}

Response samples

Content type
application/json
{
  • "__type__": "List",
  • "data": [
    ],
  • "pagination": {
    },
  • "total": 11
}

Retrieve an Admin

Fetch an Admin by its organization domain and email. The domain is generated from its organization’s name. It’s a unique and immutable value in your Cryptr service.

RETURNS

Returns the Admin for a valid identifier and email.

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 '${cryptr_service_url}/api/v2/org/${org_domain}/admins/${email}'

Response samples

Content type
application/json
{
  • "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": {
    },
  • "updated_at": "2023-06-09T16:22:44"
}

🔄 Webhook Setup

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 __type__ is a string that lets you differentiate data types.

active
boolean

Indicates whether the webhook is active.

event_codes
Array of enum

Identifiers used to specify types of events within a webhook

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": [
    ],
  • "id": "webhook_2RCVpicx8L7cFwhrz2gHjnsCLKQ",
  • "inserted_at": "2023-06-14T14:50:34",
  • "name": "My Webhook Name",
  • "signature_key": "Rjyhf8JcIfPtUhagKRKsu2Delq0JR3z6huEuJJLUwTaK8U380sA1tEgY_4aJYaRNbh_s2-u5_IWbrWQBV_DiDWAX1XNEV6DHDV8cvYGo00PkA32yWrwgEEG9ajbQ-IIT",
  • "target_url": "http://webhook.site",
  • "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.

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 -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

Content type
application/json
{
  • "__environment__": "sandbox",
  • "__type__": "Webhook",
  • "active": true,
  • "event_codes": [
    ],
  • "id": "webhook_2RCVpicx8L7cFwhrz2gHjnsCLKQ",
  • "inserted_at": "2023-06-14T14:50:34",
  • "name": "My Webhook Name",
  • "signature_key": "Rjyhf8JcIfPtUhagKRKsu2Delq0JR3z6huEuJJLUwTaK8U380sA1tEgY_4aJYaRNbh_s2-u5_IWbrWQBV_DiDWAX1XNEV6DHDV8cvYGo00PkA32yWrwgEEG9ajbQ-IIT",
  • "target_url": "http://webhook.site",
  • "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 -X DELETE '${cryptr_service_url}/api/v2/webhooks/${id}'

Response samples

Content type
application/json
{
  • "deleted": true,
  • "resource": {
    }
}

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 '${cryptr_service_url}/api/v2/webhooks' \
  -d "page=${page}" \
  -d "per_page=${per_page}" \

Response samples

Content type
application/json
{
  • "__type__": "List",
  • "data": [
    ],
  • "pagination": {
    },
  • "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 '${cryptr_service_url}/api/v2/webhooks/${id}'

Response samples

Content type
application/json
{
  • "__environment__": "sandbox",
  • "__type__": "Webhook",
  • "active": true,
  • "event_codes": [
    ],
  • "id": "webhook_2RCVpicx8L7cFwhrz2gHjnsCLKQ",
  • "inserted_at": "2023-06-14T14:50:34",
  • "name": "My Webhook Name",
  • "signature_key": "Rjyhf8JcIfPtUhagKRKsu2Delq0JR3z6huEuJJLUwTaK8U380sA1tEgY_4aJYaRNbh_s2-u5_IWbrWQBV_DiDWAX1XNEV6DHDV8cvYGo00PkA32yWrwgEEG9ajbQ-IIT",
  • "target_url": "http://webhook.site",
  • "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 -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

Content type
application/json
{
  • "__environment__": "sandbox",
  • "__type__": "Webhook",
  • "active": true,
  • "event_codes": [
    ],
  • "id": "webhook_2RCVpicx8L7cFwhrz2gHjnsCLKQ",
  • "inserted_at": "2023-06-14T14:50:34",
  • "name": "My Webhook Name",
  • "signature_key": "Rjyhf8JcIfPtUhagKRKsu2Delq0JR3z6huEuJJLUwTaK8U380sA1tEgY_4aJYaRNbh_s2-u5_IWbrWQBV_DiDWAX1XNEV6DHDV8cvYGo00PkA32yWrwgEEG9ajbQ-IIT",
  • "target_url": "http://webhook.site",
  • "updated_at": "2023-06-14T14:50:34"
}

📊 Webhook Events

The Webhook Event type

__type__
string

The __type__ is a string that lets you differentiate data types.

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:

  • available: Webhook events in the available state can be sent to your endpoint.

  • scheduled: Webhook events with scheduled_at in the future are in the scheduled state. After the scheduled_at time has elapsed, the state will become available.

  • executing: Webhook events in the executing state are currently being sent to your endpoint.

  • retryable: Webhook events in the retryable state can be resent to your endpoint after a failure.

  • completed: Webhook events in the completed state have already been sent and successfully received.

  • cancelled: Webhook events in the cancelled state have been cancelled.

  • discarded: Webhook events in the discarded state have reached their sending limits or can no longer be sent.

{
  • "__type__": "WebhookEvent",
  • "args": {
    },
  • "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 -X POST '${cryptr_service_url}/api/v2/webhook-events/${id}/cancel'

Response samples

Content type
application/json
{
  • "__type__": "WebhookEvent",
  • "args": {
    },
  • "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 or retryable.

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 '${cryptr_service_url}/api/v2/webhook-events'
  -d "page=${page}" \
  -d "per_page=${per_page}" \

Response samples

Content type
application/json
{
  • "__type__": "List",
  • "data": [
    ],
  • "pagination": {
    },
  • "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 -X POST '${cryptr_service_url}/api/v2/webhook-events/${id}/retry'

Response samples

Content type
application/json
{
  • "__type__": "WebhookEvent",
  • "args": {
    },
  • "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 -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

Content type
application/json
{
  • "__type__": "WebhookEventTest",
  • "preview": {
    },
  • "triggered_webhooks": [
    ],
  • "untriggered_webhooks": [ ]
}

🔂 Redirect URIs

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 true.

id
uuid

The immutable identifier

inserted_at
string <date-time>

Insertion datetime

updated_at
string <date-time>

Update timestamp

url
url

URL to which the user will be redirected after a successful authentication

{
  • "__environment__": "sandbox",
  • "__type__": "RedirectUri",
  • "default": false,
  • "id": "20c8da6b-8086-45f8-b767-990e5d2f8561",
  • "inserted_at": "2024-05-27T11:09:27",
  • "updated_at": "2024-05-27T11:09:27",
  • "url": "https://my-saas.app"
}

Create a Redirect URI

Create Redirect URI for an environment by specifying the url to allow redirection after successful authentication.

RETURNS

Returns Redirect URI attached to the environment if creation succeeded. Returns an error if creation failed

query Parameters
url
required
url
Example: url=https://my-saas.app

The strict URL to redirect to after successful authentication of the end-user.

Responses

Request samples 


curl -X POST '${cryptr_service_url}/api/v2/redirect_uris' \
  -d url='https://my-saas.app/api/v2/redirect_uris' \

Response samples

Content type
application/json
{
  • "__environment__": "sandbox",
  • "__type__": "RedirectUri",
  • "default": true,
  • "id": "20c8da6b-8086-45f8-b767-990e5d2f8561",
  • "inserted_at": "2024-05-27T11:09:27",
  • "updated_at": "2024-05-27T11:09:27",
  • "url": "https://my-saas.app"
}

Delete a Redirect URI

Delete a Redirect URI for an environment.

RETURNS

Returns the deleted Redirect URI for an environment/

path Parameters
id
required
uuid
Example: 20c8da6b-8086-45f8-b767-990e5d2f8561

The immutable identifier of the Redirect URI you want to retrieve

Responses

Request samples 

curl -X DELETE '${cryptr_service_url}/api/v2/:id'

Response samples

Content type
application/json
{
  • "deleted": true,
  • "resource": {
    }
}

List all Redirect URIs

Return a list of all Redirect URI for the environment according to the expected pagination.

RETURNS

A dictionary with data that contains an array of up to the limit of Redirect URI. Each entry in the array represents a separate Redirect URI type. If no matching Redirect URI is 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=2

Precise the size of the pages of the pagination of the list.

Responses

Request samples 

curl -X '${cryptr_service_url}/api/v2/redirect_uris'

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    },
  • "total": 0
}

Retrieve a Redirect URI

Retrieve a Redirect URI by specifying its given id.

RETURNS

Returns a Redirect URI for a valid identifier. If no match is found, a Not Found error will be returned.

path Parameters
id
required
uuid
Example: 20c8da6b-8086-45f8-b767-990e5d2f8561

The immutable identifier of the Redirect URI you want to retrieve

Responses

Request samples 

curl -X '${cryptr_service_url}/api/v2/:id'

Response samples

Content type
application/json
{
  • "__environment__": "sandbox",
  • "__type__": "RedirectUri",
  • "default": true,
  • "id": "20c8da6b-8086-45f8-b767-990e5d2f8561",
  • "inserted_at": "2024-05-27T11:09:27",
  • "updated_at": "2024-05-27T11:09:27",
  • "url": "https://my-saas.app"
}

Set Redirect URI as default

Set a Redirect URI for its environment.

When a Redirect URI is the default of the environment, it cannot be deleted until another one is set as default. For each authentication request that has no redirect URI provided, the default Redirect URI will be used according to the request’s environment.

RETURNS

Returns the Redirect URI with default set to true if the request succeeds.

path Parameters
id
required
uuid
Example: 20c8da6b-8086-45f8-b767-990e5d2f8561

The immutable identifier of the Redirect URI you want to retrieve

Responses

Request samples 

curl -X PUT '${cryptr_service_url}/api/v2/:id/set-as-default'

Response samples

Content type
application/json
{
  • "__environment__": "sandbox",
  • "__type__": "RedirectUri",
  • "default": true,
  • "id": "20c8da6b-8086-45f8-b767-990e5d2f8561",
  • "inserted_at": "2024-05-27T11:09:27",
  • "updated_at": "2024-05-27T11:09:27",
  • "url": "https://my-saas.app"
}

🔐 Token

The Token type

The token is used to authorize access to a given service. This could be, for example, authorizing a user to access a service or authorizing a request to communicate with an API.

access_token
string

Token used to allow access to an application.

expires_in
string

The token’s validity period.

id_token
boolean
Default: false

Token used to store user profile information.

scope
boolean
Default: false

The scope of the token. This can be the resource to which a user has access.

token_type
string

The type of the Token, for example, Bearer

{
  • "access_token": "eyJhbGciOiJSUzI1NiIsImlzcyI6Imh0...",
  • "expires_in": 36000,
  • "id_token": "eyJhbGciOiJSUzI1NiIsImlzcyI6Imh0...",
  • "scope": [
    ],
  • "token_type": "Bearer"
}

The MetaKey type

When an authentication is successful (after a successful Magic Link or SSO Connection process), JWT are generated to authenticate and identify User.

These tokens can be customized with Metadata. To do so you first need to declare a MetaKey to use it on your User resource. If you already have a declared MetaKey and you want to add MetaData to a User the corresponding documentation is in the User Tab.

name
string

The desired name for this new MetaKey, use something understandable for your use case.

required
string

A boolean that indicates if the key is required.

type
string

The type of the data that will be used as value.

{
  • "name": "uid",
  • "required": false,
  • "type": "string"
}

Create a Token

Create a Token.

RETURNS

Returns the Access Token, ID Token...

query Parameters
audience
string
Example: audience=loirama

The audience is, in most cases, the Account Domain.

client_id
uuid
Example: client_id=2fd63d8d-8f1d-42f2-9b13-9e698b821e4f

The Client ID is your API Key ID.

client_secret
string
Example: client_secret=my-secret

The Client Secret is your API Key secret.

code
string
Example: code=9ukVAuUcYrxPe4VYW5yFLjnP6NBV6a82MMm8FwyV6UUH4hQg4a

The code that allows you to generate a token. This code is often obtained after a successful challenge.

grant_type
required
enum
Enum: "authorization_code" "relay" "client_credentials"
Example: grant_type=authorization_code

The Grant Type of your request

Responses

Request samples 


curl -X POST '${cryptr_service_url}/oauth/token' \
  -d grant_type='client_credentials' \
  -d client_id='2fd63d8d-8f1d-42f2-9b13-9e698b821e4f' \
  -d client_secret='my-secret'

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJSUzI1NiIsImlzcyI6Imh0...",
  • "expires_in": 36000,
  • "id_token": "eyJhbGciOiJSUzI1NiIsImlzcyI6Imh0...",
  • "scope": [
    ],
  • "token_type": "Bearer"
}

Create a User Metakey

Define a MetaKey with a specific name that applies to all users within each of your organizations. You can later use these special fields to store data you need in your application. You choose what you want to store and under what key. This way if the basic fields of Cryptr are not sufficient you can add your own fields.

The field will be available in the Tokens, if the User have an associated value in this Key, after a successful user authentication.

RETURNS

The allowed Metakey you just created. You can now specify the value of this key on any User, from any Organization.

query Parameters
name
required
string
Example: name=uid

The desired name for this new MetaKey, use something understandable for your use case

Responses

Request samples 


curl -X POST '${cryptr_service_url}/api/v2/tokens/user-metakeys' \
  -d key='uid'

Response samples

Content type
application/json
{
  • "name": "uid",
  • "required": false,
  • "type": "string"
}

List all User Metakeys

List all stored user MetaKey.

RETURNS

The list of all user MetaKey available on your service

Responses

Request samples 


curl -X GET '${cryptr_service_url}/api/v2/tokens/user-metakeys'

Response samples

Content type
application/json
[
  • {
    }
]

Remove a User MetaKey

Use the below request when a MetaKey is no more useful. While the Metakey is being deleted the Key will be locked and no operation can be used on this key.

RETURNS

The deleted Key Metadata with a confirmation it is deleted.

query Parameters
name
required
string
Example: name=uid

The name of the MetaKey

Responses

Request samples 


curl -X GET '${cryptr_service_url}/api/v2/tokens/user-metakeys' \
  -d key='uid'

Response samples

Content type
application/json
{
  • "deleted": true,
  • "resource": {
    }
}