Skip to main content
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 are 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 get 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 which lets you differentiate data type.

allowed_email_domains
Array of strings or null

Current allowed email domain(s) that organization users can use 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 "underline", 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" & store 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 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" & store into 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

Domain is a STRING value in "lowercase" with "dash", generated from the organization name.

Responses

Request samples 


curl -X DELETE
  '${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"
}

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 limit Organizations. Each entry in the array is 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 by its given domain. The domain is generated from its name. It's a unique and immutable value in your Cryptr service.

RETURNS

Returns the Organization for a valid identifier. If it’s for a deleted Organization, a subset of the Organization’s information is returned, including a deleted property that’s set to true.

path Parameters
org_domain
required
string
Example: weeklymotion

Domain is a STRING value in "lowercase" with "dash", generated from the organization 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 create parameters are invalid (e.g. specifying an invalid code or an invalid source).

path Parameters
org_domain
required
string
Example: weeklymotion

Domain is a STRING value in "lowercase" with "dash", generated from the organization name.

query Parameters
name
string
Example: name=Weeklymotion

The name of your organization (won't change domain because already set at creation)

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 for a dedicated customer (Organization). You can figure out the domain of the user's Organization from this user's atttribute domain.

The User type

Each new user get a unique id (identifier) generated and which is impossible to update.

__domain__
string

Domain is a STRING value in "lowercase" with "dash", generated from the organization name.

__environment__
string

Environment in which the user is stored, either sandbox (for the test environment) or production

__type__
string

Data type

object (Address)

User's postal address. The value of the address member is a Address type defined here.

email
string <email>

Email

email_verified
boolean

Boolean that indicates if the email has been verified

id
uuid

The immutable identifier.

inserted_at
string <date-time>

Insertion date time

metadata
Array of arrays
phone_number
string

User telephone number as E.164 format.

phone_number_verified
boolean

Boolean that indicates if the phone number has been verified

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",
  • "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"
}

The Profile type

birthdate
string

User's birthday represented as an ISO 8601:2004 [ISO8601-2004] YYYY-MM-DD format.

family_name
string

The last name is an Open Id Connect Profile attribute.

gender
enum

It's an Open Id Connect Profile attribute.

given_name
string

The first name is an Open Id Connect Profile attribute.

locale
enum

It's an Open Id Connect Profile attribute.

nickname
string

It's an Open Id Connect Profile attribute.

picture
url

It's an Open Id Connect Profile attribute.

preferred_username
string or null

It's an Open Id Connect Profile attribute.

website
url

It's an Open Id Connect Profile attribute.

zoneinfo
enum

It's an Open Id Connect Profile attribute.

{}

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 (" ") or as a single line feed character (" ").

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 (" ") or as a single line feed character (" ").

{
  • "country": "FR",
  • "formatted": "165 avenue de Bretagne\n59000 Lille, France",
  • "locality": "Lille",
  • "postal_code": "59000",
  • "region": "Nord",
  • "street_address": "165 avenue de Bretagne"
}

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 create parameters are invalid (e.g. specifying an invalid code or an invalid source).

path Parameters
org_domain
required
string
Example: loirama

Domain is a STRING value in "lowercase" with "dash", generated from the organization 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 a Address type defined here.

email
required
string
Example: email=lyla@loirama.co

Email is a required field as it is part of the security of the created end-user account.

birthdate
string
Example: birthdate=1992-03-10

User's birthday represented as an ISO 8601:2004 [ISO8601-2004] YYYY-MM-DD format.

phone_number
string
Example: phone_number=+33123456789

User telephone number as E.164 format.

given_name
string
Example: given_name=Lyla

The first name is an Open Id Connect Profile attribute.

family_name
string
Example: family_name=Bloggs

The last name is an Open Id Connect Profile attribute.

nickname
string
Example: nickname=lylaB

It's an Open Id Connect Profile attribute.

picture
string <url>
Example: picture=http://www.example.com/avatar.jpeg

It's an Open Id Connect Profile attribute.

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

It's an Open Id Connect Profile attribute.

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

It's an Open Id Connect Profile attribute, available options are male, female or null.

zoneinfo
string
Example: zoneinfo=France/Lille

It's an Open Id Connect Profile attribute.

locale
string
Example: locale=fr

It's an Open Id Connect Profile attribute.

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

Response samples

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

Delete a User By ID

Delete an existing user.

RETURNS

Returns a deleted Users from an Organization.

path Parameters
org_domain
required
string
Example: b-oreal

Domain is a STRING value in "lowercase" with "dash", generated from the organization 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. The Users are returned 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 is 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

Domain is a STRING value in "lowercase" with "dash", generated from the organization 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
}

Retrieve a User By Email or ID

Fetch a User by its given email or id.

RETURNS

Returns a User for a valid email or a valid identifier. If it’s for a deleted User, a subset of the User’s information is returned, including a deleted property that’s set to true.

path Parameters
org_domain
required
string
Example: loirama

Domain is a STRING value in "lowercase" with "dash", generated from the organization name.

email_or_id
required
string
Example: janis.joplin@example.com or 86561a93-bee2-4eba-96ff-6769d617eaf8

The user's email or the user's id (uuid).

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",
  • "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"
}

Update a User

Update an existing user.

RETURNS

Returns an updated Users from an Organization if the update succeeded. Returns an error if create parameters are invalid (e.g. specifying an invalid code or an invalid source).

path Parameters
org_domain
required
string
Example: loirama

Domain is a STRING value in "lowercase" with "dash", generated from the organization 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 a Address type defined here.

email
required
string
Example: email=lyla@loirama.co

Email is a required field as it is part of the security of the created end-user account.

birthdate
string
Example: birthdate=1992-03-10

User's birthday represented as an ISO 8601:2004 [ISO8601-2004] YYYY-MM-DD format.

phone_number
string
Example: phone_number=+33123456789

User telephone number as E.164 format.

given_name
string
Example: given_name=Lyla

The first name is an Open Id Connect Profile attribute.

family_name
string
Example: family_name=Bloggs

The last name is an Open Id Connect Profile attribute.

nickname
string
Example: nickname=lylaB

It's an Open Id Connect Profile attribute.

picture
string <url>
Example: picture=http://www.example.com/avatar.jpeg

It's an Open Id Connect Profile attribute.

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

It's an Open Id Connect Profile attribute.

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

It's an Open Id Connect Profile attribute, available options are male, female or null.

zoneinfo
string
Example: zoneinfo=France/Lille

It's an Open Id Connect Profile attribute.

locale
string
Example: locale=fr

It's an Open Id 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]="http://www.example.com/avatar.jpeg"'
        --form 'profile[website]="http://www.example.com"'
        --form 'profile[gender]="female"'
        --form 'profile[zoneinfo]="France/Lille"'
        --form 'profile[locale]="fr"'

Response samples

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

🔄 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 if a user is created the change will be automatically taken into account and propagated. The SCIM takes into account creations as well as deletions or updates.

The Directory Sync type

The number of directory syncs you can create is limited. You can only create one Directory Sync per organization domain and environment pair. For example if your organization domain is "misapret" and you have a "sandbox" environment you can only create a Directory Sync for "misapret/sandbox". But if you also have a "production" environment, you can then 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 "underline", generated from the name.

__environment__
string

Environment in which the user is stored, either sandbox (for the test environment) or production

__type__
string

The __type__ is a String which lets you differentiate data type.

object (AuthSecretToken)

Use value as Bearer token for your SCIM implementation in your provider.

💡 Only available once at creation so save it. To get a new one you will have 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
string

The name of the provider you use, e.g. 'okta', 'ping_one', 'azure_ad'

updated_at
string <date-time>

Update timestamp

{
  • "__domain__": "barker-inc",
  • "__environment__": "sandbox",
  • "__type__": "DirectorySync",
  • "auth_secret_token": {
    },
  • "id": "32dad740-142e-4af3-ac69-de5f36915d80",
  • "inserted_at": "2023-06-15T09:23:55",
  • "provider": "okta",
  • "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 get the associated bearer token. Keep it safe. If you lose your bearer token you will have to reset it.

Note: When you create a Directory Sync, the environment of your API key determine where is stored your Directory Sync. For exemple your Directory Sync in sandbox is created if and only if this resource is stored in sandbox. You can't create a Directory Sync from the Production environment with this API KEY, you need an API KEY dedicated to this environment.

path Parameters
org_domain
required
string
Example: barker-inc

Domain is a STRING value in "lowercase" with "dash", generated from the organization name.

query Parameters
provider
required
string
Example: provider=okta

The provider name e.g. 'okta', 'azure_ad', 'ping_one'...

Responses

Request samples 


curl -X POST '${cryptr_service_url}/api/v2/org/${org_domain}/directory-sync' \
  -d "provider=okta"

Response samples

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

Delete a Directory Sync

Use the below request when you want to delete a Directory Sync

RETURNS

The deleted Directory sync

path Parameters
org_domain
required
string
Example: misapret

Domain is a STRING value in "lowercase" with "dash", generated from the organization name.

Responses

Request samples 


curl -X DELETE '${cryptr_service_url}/api/v2/org/${org_domain}/directory-sync'

Response samples

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

Reset a Directory Sync

Reset an existing Directory Sync in an Organization. When you reset a Directory Sync you will get a new associated bearer token. Keep it safe. If you lose your bearer token you will have to reset it again. The reset endpoint is useful for you to create a new bearer token. Only use it if you lost your previous bearer token.

Note: The Bearer Token will only be returned in clear text when your Directory Sync is created. This endpoint allows you to create a new one (the previous one will then be unusable). As during creation, the token will only be displayed once. In other cases the bearer token will not be displayed in clear text.

path Parameters
org_domain
required
string
Example: misapret

Domain is a STRING value in "lowercase" with "dash", generated from the organization name.

Responses

Request samples 


curl -X PUT '${cryptr_service_url}/api/v2/org/${org_domain}/directory-sync/reset'

Response samples

Content type
application/json
{
  • "__domain__": "barker-inc",
  • "__environment__": "sandbox",
  • "__type__": "DirectorySync",
  • "auth_secret_token": {
    },
  • "id": "32dad740-142e-4af3-ac69-de5f36915d80",
  • "inserted_at": "2023-06-15T09:23:55",
  • "provider": "okta",
  • "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 determine where is stored your Directory Sync. For exemple your Directory Sync in sandbox is fetched if and only if this resource is stored in sandbox. You can't fetch a Directory Sync from the Production environment with this API KEY, you need an API KEY dedicated to this environment.

RETURNS

Returns the Directory Sync for a valid organization/environment pair. If it’s for a deleted Directory Sync, a response of NoResult is displayed.

path Parameters
org_domain
required
string
Example: misapret

Domain is a STRING value in "lowercase" with "dash", generated from the organization 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",
  • "auth_secret_token": {
    },
  • "id": "32dad740-142e-4af3-ac69-de5f36915d80",
  • "inserted_at": "2023-06-15T09:23:55",
  • "provider": "ping_one",
  • "updated_at": "2023-06-15T12:11:17"
}

Update a Directory Sync

Update an existing Directory Sync in an Organization. The only thing that you can update is your provider. For example if your previous provider was okta and you are now on an azure_ad solution.

Note: A new bearer token will be assigned when updating your Directory Sync. The previous token will then be unusable. This is for security reasons. If you only want to update your Bearer Token because you lost it please consider using the reset endpoint.

path Parameters
org_domain
required
string
Example: misapret

Domain is a STRING value in "lowercase" with "dash", generated from the organization name.

query Parameters
provider
required
string
Example: provider=okta

The provider name e.g. 'okta', 'azure_ad', 'ping_one'...

Responses

Request samples 


curl -X PUT '${cryptr_service_url}/api/v2/org/${org_domain}/directory-sync' \
  -d "provider=ping_one"

Response samples

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

🔐 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 the 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"
}

Create a Token

Create a Token.

RETURNS

Returns the Access Token, ID Token...

query Parameters
audience
string
Example: audience=loirama

The audience it is in most of the case 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=4kimQW4Xp5QR6HXGyqWrNxLQL3rVmpKKnTCCLdEH5p1S1qDDDJpnL2qR54dP

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='4kimQW4Xp5QR6HXGyqWrNxLQL3rVmpKKnTCCLdEH5p1S1qDDDJpnL2qR54dP'

Response samples

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

🔌 SSO

You can create or update SSO connection preferences for an Organization (usualy your Enterprise customer). Everything to setup, attach, create a redirection a end-user login or interact with 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
  • One Login
  • 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 will be updated from the identity provider only on user profile creation.

You can add & edit root attributes individually or as a bulk import using the Management API. You'll find these attributes in the final JWT (Json Web Token) after the successfull SSO authentifcation.

  • A (User) represents an end user ofr your customer or partner in your Cryptr service.

Your Cryptr subscription plan could limit the number of users. See our pricing for more details.

__type__
string

The __type__ is a String which lets you differentiate data type.

active
boolean
Default: true

Define if the connection is usable or not

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 ...) of 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 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 in 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).

{}

Before you can create an SSO challenge, it is essential to first set up an SSO connection.

SSO challenge is a secure validation process for single sign-on. It involves an authentication request sent to the user, who must pass a challenge to prove his identity and access SSO-protected services.

The SSO Challenge type

__environment__
string

Environment in which the user is stored, either sandbox (for the test environment) or production

__type__
string

The __type__ is a String which lets you differentiate data type.

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 identifier associated with the creation of a SSO challenge. It allows to follow this specific request throughout the single sign-on process.

sso_connection_id
string

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

Domain is a STRING value in "lowercase" with "dash", generated from the organization 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-challenges' \
  -d user_email="lyla@loirama.co" \
  -d redirect_uri="https://loirama.com/welcome-back-user" \
  // Use the following option if you prefer to use org_domain instead of user_email \
  // -d org_domain="loirama"

Response samples

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

Domain is a STRING value in "lowercase" with "dash", generated from the organization 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-challenges' \
  -d user_email="lyla@loirama.co" \
  -d redirect_uri="https://loirama.com/welcome-back-user" \
  // Use the following option if you prefer to use org_domain instead of user_email \
  // -d org_domain="loirama"

Response samples

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 auto expand onboarding nested element

RETURNS

Returns an SSO Connection if the creation succeed.

path Parameters
org_domain
required
string
Example: well-agency

Domain is a STRING value in "lowercase" with "dash", generated from the organization name.

query Parameters
provider_type
string
Default: "unset"
Enum: "unset" "ping_federate" "ping_one" "azure_ad" "okta" "google" "adfs" "keycloak" "ibm_security_verify" "onelogin"
Example: provider_type=azure_ad

Change the provider type (Okta, Google Workspace, ADFS ...) of targetted Sso Connection

number_users_provisioning_limit
integer

Change the limit of simultaneously possible sso sessions for the targetted Sso Connection

⚠️ Depending on 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 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
{}

Delete an SSO Connection

Delete an SSO Connection.

RETURNS

Returns a deleted SSO Connection from an Organization.

path Parameters
org_domain
required
string
Example: barker-inc

Domain is a STRING value in "lowercase" with "dash", generated from the organization name.

Responses

Request samples 


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

Response samples

Content type
application/json
{}

List all SSO Connections

List all your SSOConnection currently created, regardless of the progress of the configuration.

RETURNS

Returns list of SSO Connection with nested objects if preload_associations set and paginated if related attributes

path Parameters
org_domain
required
string
Example: lalylala

Domain is a STRING value in "lowercase" with "dash", generated from the organization name.

query Parameters
page
integer
Example: page=1

Precise the page of your listing, see how to paginate the Cryptr API.

per_page
integer
Example: per_page=2

Precise the size of the pages of the pagination of the list. See how to paginate the Cryptr API.

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

Retrieve an SSO Connection

Fetch an SSO Connection, usefull to known its configuration and also fetch nested object onboarding.

RETURNS

Returns the SSO Connection

path Parameters
org_domain
required
string
Example: lalylala

Domain is a STRING value in "lowercase" with "dash", generated from the organization name.

Responses

Request samples 

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

Response samples

Content type
application/json
{}

Update a SSO Connection

Fetch an SSO Connection, usefull to known its configuration and also fetch nested object onboarding.

RETURNS

Returns the updated SSO Connection

path Parameters
org_domain
required
string
Example: lalylala

Domain is a STRING value in "lowercase" with "dash", generated from the organization name.

query Parameters
active
boolean
Example: active=true

Change the state of the SSO Connection see Turn on/off 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 targetted Sso Connection.

For example if the SSO Administrator send you a new XML Metadata for the connection you can change it here.

provider_type
string
Example: provider_type=azure_ad

Change the provider type (Okta, Google Workspace, ADFS ...) of targetted Sso Connection

number_users_provisioning_limit
integer

Change the limit of simultaneously possible sso sessions for the targetted Sso Connection

⚠️ Depending on users_access_policy value

users_access_policy
string
Example: users_access_policy=provision_new_users

Change the rule of end-user openning session for the targetted Sso Connection

preload_associations
Array of strings

By default all nested resources are returned by their ids. If you would like the nested object returned in the body, you can set enterprise_connection_onboarding into this parameter.

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

🔑 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

Domain is a STRING value in "lowercase" with "dash", generated from the organization name.

__environment__
string

Environment in which the user is stored, either sandbox (for the test environment) or production

__type__
string

The __type__ is a String which lets you differentiate data type.

code
string

The code is used to retrieve 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

Domain is a STRING value in "lowercase" with "dash", generated from the organization name.

__type__
string

The __type__ is a String which lets you differentiate data type.

active
boolean
Default: true

Define if the connection is usable or not

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

Domain is a STRING value in "lowercase" with "dash", generated from the organization name.

__environment__
string

Environment in which the user is stored, either sandbox (for the test environment) or production

__type__
string

The __type__ is a String which lets you differentiate data type.

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

Domain is a STRING value in "lowercase" with "dash", generated from the organization 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

Domain is a STRING value in "lowercase" with "dash", generated from the organization 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

Domain is a STRING value in "lowercase" with "dash", generated from the organization 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

Domain is a STRING value in "lowercase" with "dash", generated from the organization 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

Domain is a STRING value in "lowercase" with "dash", generated from the organization 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

Domain is a STRING value in "lowercase" with "dash", generated from the organization 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 his identity and access protected services.

The TOTP Challenge type

__type__
string

The __type__ is a String which lets you differentiate data type.

challenged_at
string

The date on which the validation of the challenge 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 value will be true. If true you should re-enroll your user.

request_id
string

The unique identifier of the request, creation and validation have different request_id

sent_at
string

The Date on which the Challenge was created.

success
boolean

The success of the challenge. Will be false at creation, 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 (usualy your Enterprise customer).

The TOTP Connection type

__domain__
string

Domain is a STRING value in "lowercase" with "dash", generated from the organization name.

active
boolean

Determines if the Connection is active or not

expiry_in_seconds
integer

The expiration time of the TOTP. By default, 30 sec for TOTP Mobile App & 600 sec for SMS.

method
string

The Method that 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 user to TOTP.

The TOTP Enrollment type

__domain__
string

Domain is a STRING value in "lowercase" with "dash", generated from the organization name.

__environment__
string

Environment in which the user is stored, either sandbox (for the test environment) or production

__type__
string

The __type__ is a String which lets you differentiate data type.

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 enrollment for a user.

first_verification_code
string

The code that the user should use for SMS Enrollment Validation.

Only displayed at creation for SMS Method.

last_recovery_acknowledgement_at
string

The last date on which the user acknowledged receipt of his recovery codes

last_recovery_code_at
string

The Last Date on which the user used a recovery code.

recovery_codes
string

The recovery codes of the user. The codes are generated only one time unless user is force enrolled.

Each code is separated by '\n'

uri
string

The URI that should be used to enroll to a mobile TOTP App. Only displayed for 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 strengthen security. Useful only for the SMS method to generate a code to send to your users by SMS.

RETURNS

Returns information such as the request_id, code, the validity, and other information associated with the Challenge created.

path Parameters
org_domain
required
string
Example: loirama

Domain is a STRING value in "lowercase" with "dash", generated from the organization 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 enroll a user to MFA (TOTP).

RETURNS

Returns information such as the enrollment_nb, enrolled_at, the validity, and other information associated with the Enrollment created.

path Parameters
org_domain
required
string
Example: loirama

Domain is a STRING value in "lowercase" with "dash", generated from the organization name.

Please note that 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 he used all his recovery codes, set this value to true.

Also generate five new recovery codes when activated

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

Domain is a STRING value in "lowercase" with "dash", generated from the organization 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 this one 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

Domain is a STRING value in "lowercase" with "dash", generated from the organization name.

query Parameters
active
boolean
Default: false
Example: active=true

A 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 600 seconds for SMS method (10 minutes). Default 30 seconds for 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. It is therefore strongly recommended to keep the default validity time of 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 enter 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

Domain is a STRING value in "lowercase" with "dash", generated from the organization 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 TOTP Code of the user 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 enter on your app. If the user is able to enter a valid code we assume that they have registered their QR Code on 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

Domain is a STRING value in "lowercase" with "dash", generated from the organization name.

Please note that 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 TOTP Code of the user 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 his side by accessing the Onboarding.

When created the Admin will directly receive a magic link email to its onboarding.

accepted_invitation_at
string or null <date-time>

Date and time of when the Admin accepted the invitation

color
string

The Logo Color of the Admin 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 date time

invited_at
string <date-time>

The Date and Time when the Admin was invited (creation date)

last_login_at
string or null <date-time>

Date and time of the last login of the Admin

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 get in response.

A long TTL Invitation Link is sent by Email to the Admin when created

RETURNS

The created Admin with proper attributes

path Parameters
org_domain
required
string
Example: shark-academy

Domain is a STRING value in "lowercase" with "dash", generated from the organization 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 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

Domain is a STRING value in "lowercase" with "dash", generated from the organization 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

Domain is a STRING value in "lowercase" with "dash", generated from the organization 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 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

Domain is a STRING value in "lowercase" with "dash", generated from the organization 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 of what is happening on your App or Directory Sync.

For example if a user is created the change will be automatically taken into account and the details will be sent to your target url. Several actions are taken into account such as updating, deleting or creating resources.

The Webhook type

You can create one or more Webhooks for an organization domain and environment pair. For example if your organization domain is "misapret" and you have a "sandbox" environment you can create a Webhook for "misapret/sandbox". But if you also have a "production" environment, you will only receive information that takes place in your "sandbox" environment. To be able to also receive those coming from your "production" environment it will be necessary to create a new webhook.

__environment__
string

Environment in which the user is stored, either sandbox (for the test environment) or production

__type__
string

The __type__ is a String which lets you differentiate data type.

active
boolean

Indicates whether the webhook is active or not.

event_codes
Array of enum

Identifiers used to specify types of events within a webhook, see full list of events

id
string

A unique string that identifies a specific webhook.

inserted_at
string

Insertion date time

name
string

The name of your webhook, a label to help you to understand which webhook is about.

signature_key
string

This value will make it possible to guarantee the integrity of the response and to authenticate the author.

target_url
string

Refers to the specific URL where you want to receive event information.

updated_at
string

Updated date time

{
  • "__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 own Organization. When you create a Webhook you will get the associated signature key.

Note: When you create a Webhook, the environment of your API key determine where is stored your Webhook. For exemple your Webhook in sandbox is created if and only if this resource is stored in sandbox. You can't create a Webhook from the Production environment with this API KEY, you need an API KEY dedicated to this environment.

query Parameters
name
required
string
Example: name=My Webhook Name

The name of your webhook you can set it to anything you want

event_codes[]
required
Array of strings
Example: event_codes[]=dir_sync.user.provision.success

Identifiers used to specify types of events within a webhook, see full list of events

target_url
required
string
Example: target_url=http://webhook.site

Refers to the specific URL where you want to receive event information.

Responses

Request samples 


curl -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 below request 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 determine where are stored your Webhooks. For exemple your Webhooks in sandbox are fetched if and only if the resources are stored in 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 there is no Webhook 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 determine where is stored your Webhook. For exemple your Webhook in sandbox is fetched if and only if this resource is stored in sandbox. You can't fetch a Webhook from the Production environment with this API KEY, you need an API KEY dedicated to this environment.

RETURNS

Returns the Webhook for a valid organization/environment pair. If it’s for a deleted Webhook, a response of not found 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 your Hook 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 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.

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"

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 which lets you differentiate data type.

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 on which the event sending was discarded.

id
string

Immutable identifier. Here it is the slug version of the name

inserted_at
string <date-time>

Insertion date time

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 that have the states available can be sent to your endpoint.

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

  • executing Webhook Events that have the states executing are being sent to your endpoint.

  • retryable Webhook Events that have the states retryable can be sent again to your endpoint after a failure.

  • completed Webhook Events that have the states completed have already been sent and successfully received.

  • cancelled Webhook Events that have the states cancelled have been cancelled.

  • discarded Webhook Events that have the states discarded 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 cancelled 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 'cancelled'.

RETURNS

The cancelled job. If the Webhook Events your requested for cancel doesn'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 life span. 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 the retry when we have taken into account your request. If not, 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 your requested for retry doesn'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}/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 the event codes are available to test.

RETURNS

The preview of the event you should receive. If no webhook is linked to this event_code, the preview will be nil. As well as 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 send 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": [ ]
}
Logo de Cryptr
Consult our Changelog