[Skip to main content](/content/documentation/api/#__docusaurus_skipToContent_fallback/index.html)

- User Directories
  - 🧑‍🤝‍🧑 Organizations
    - postCreate an Organization
    - delDelete an Organization
    - getList all Organizations
    - getRetrieve an Organization
    - putUpdate an Organization
  - 👩‍💻 Users
    - putAdd User Metadata
    - postCreate a User
    - delDelete a User By ID
    - getList all Users
    - putRemove User Metadata
    - getRetrieve a User By Email or ID
    - putUpdate a User
  - 🔄 Directory Syncs
    - postCreate a Directory Sync
    - getRetrieve a Directory Sync
    - putUpdate a Directory Sync
- Authentications
  - 🔌 SSO
    - postCreate an SSO Challenge
    - postCreate an SSO Connection
    - getList all SSO Connections
    - getRetrieve an SSO Connection
    - putUpdate an SSO Connection
  - 🔑 Password
    - postCreate a new Password
    - postCreate a Password Challenge
    - postCreate a Password Connection
    - postRequest a new Password via Magic Link
    - getRetrieve a Password Connection
    - putUpdate a Password Connection
  - ✨ Magic Link
    - postCreate a Magic Link Challenge
    - getRetrieve a Magic Link Connection
    - putUpdate a Magic Link Connection
  - 🔑 TOTP
    - postCreate a TOTP Challenge
    - postCreate a TOTP Enrollment
    - getRetrieve a TOTP Connection
    - putUpdate a TOTP Connection
    - putValidate a TOTP Challenge
    - putValidate a TOTP Enrollment
- Admins
  - ⚙️ Admin
    - postCreate the Admin
    - delDelete an Admin
    - getList all Admins
    - getRetrieve an Admin
- Others
  - 🔄 Webhook Setup
    - postCreate a Webhook
    - delDelete a Webhook
    - getList all Webhooks
    - getRetrieve a Webhook
    - putUpdate a Webhook
  - 📊 Webhook Events
    - postCancel Webhook Event
    - getList Webhook Events
    - postRetry Webhook Event
    - postTest Webhook Event
  - 🔂 Redirect URIs
    - postCreate a Redirect URI
    - delDelete a Redirect URI
    - getList all Redirect URIs
    - getRetrieve a Redirect URI
    - putSet Redirect URI as default
  - 🔐 Token
    - postCreate a Token
    - postCreate a User Metakey
    - getList all User Metakeys
    - delRemove a User MetaKey

API docs by Redocly](https://redocly.com/redoc/)

# API reference (2.0)

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

## [tag/Organizations](/content/documentation/api/\#tag/Organizations/index.html) 🧑‍🤝‍🧑 Organizations

The [Organizations](/content/documentation/api/#the-organization-type/index.html) 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](/content/documentation/api/#the-organization-type/index.html)) represents a business customer or partner in your Cryptr service.

- An ( [Organization](/content/documentation/api/#the-organization-type/index.html)) 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<br>The `__type__` is a **string** that lets you differentiate data types. |
| allowed\_email\_domains | Array of strings or null<br>Current allowed email domain(s) for organization users to log in. |
| color | string<br>The color of your organization’s logo in your Cryptr Dashboard. |
| domain | slug<br>Immutable identifier of the organization in a ' **slug** format': domain is a **string** value in lowercase with underscores, generated from the name. |
| environments | Array of objects (Environment) <br>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<br>The URL of your organization’s logo in icon format. |
| inline\_logo\_url | string<br>The URL of your organization’s logo in inline format |
| inserted\_at | string <date-time> <br>Date time of the insertion |
| locale | string<br>Your organization’s preferred locale |
| name | string<br>The name of your organization will be **sluggified** and stored at the `domain` field. 'Awesome company' will become 'awesome-company'. |
| status | object (Status) <br>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<br>Your organization’s preferred timezone |
| updated\_at | string <date-time> <br>Update timestamp |

Copy
Expand all  Collapse all

`{"__type__": "Organization",

"allowed_email_domains": ["weeklymotion.com"\
\
],

"color": "red-500",

"domain": "weeklymotion",

"environments": [{"name": "production",\
\
"status": "down"\
\
},\
\
{"name": "sandbox",\
\
"status": "down"\
\
}\
\
],

"icon_logo_url": "https://...",

"inline_logo_url": "https://...",

"inserted_at": "2023-05-10T06:16:35",

"locale": "en-US",

"name": "Weeklymotion",

"status": {"errors": [ ],

"estimated_time_to_complete_in_seconds": null,

"progress_in_percentage": null,

"state": "pending"

},

"timezone": "Coordinated Universal Time (UTC)",

"updated_at": "2023-05-10T06:16:35"

}`

## [tag/Organizations/operation/create-organization](/content/documentation/api/\#tag/Organizations/operation/create-organization/index.html) Create an Organization

Creates a new Organization type with a name.

#### RETURNS

Returns an [Organization](/content/documentation/api/#the-organization-type/index.html) 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<br>required | string<br>Example: name=Weeklymotion<br>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<br>Example: allowed\_email\_domains\[\]=weeklymotion.com<br>List of email domains from the professional emails of the users |

### Responses

**201**

Created

**422**

Unprocessable Entity

post/api/v2/organizations

https://${{cryptr\_service\_url}}/api/v2/organizations

### Request samples

- cURL

Copy

```
curl -X POST ${cryptr_service_url}/api/v2/organizations \
  -H "Authorization: Bearer your-access-token-from-client-id-and-secret" \
  -d name="Communitiz App" \
  -d allowed_email_domains[]="communitz-app"
```

### Response samples

- 201
- 422

Content type

application/json

Copy
Expand all  Collapse all

`{"__type__": "Organization",

"allowed_email_domains": ["weeklymotion.com"\
\
],

"color": "red-500",

"domain": "weeklymotion",

"environments": [{"name": "production",\
\
"status": "down"\
\
},\
\
{"name": "sandbox",\
\
"status": "down"\
\
}\
\
],

"icon_logo_url": "https://...",

"inline_logo_url": "https://...",

"inserted_at": "2023-05-04T07:16:56",

"locale": "en-US",

"name": "Weeklymotion",

"status": {"errors": [ ],

"estimated_time_to_complete_in_seconds": null,

"progress_in_percentage": null,

"state": "pending"

},

"timezone": "Coordinated Universal Time (UTC)",

"updated_at": "2023-05-04T07:16:56"

}`

## [tag/Organizations/operation/delete-organization](/content/documentation/api/\#tag/Organizations/operation/delete-organization/index.html) Delete an Organization

Delete an Organization with a domain.

#### RETURNS

Returns the deleted [Organization](/content/documentation/api/#the-organization-type/index.html).

##### path Parameters

|     |     |
| --- | --- |
| org\_domain<br>required | string<br>Example: weeklymotion<br>The domain is a **string** value in **lowercase** with **dashes**, generated from the organization’s name. |

### Responses

**200**

OK

**401**

Unauthorized

delete/api/v2/organizations/{org\_domain}

https://${{cryptr\_service\_url}}/api/v2/organizations/{org\_domain}

### Request samples

- cURL

Copy

```
curl -X DELETE
  '${cryptr_service_url}/api/v2/organizations/${org_domain}'
```

### Response samples

- 200
- 401

Content type

application/json

Copy
Expand all  Collapse all

`{"deleted": true,

"resource": {"__type__": "Organization",

"allowed_email_domains": ["weeklymotion.com"\
\
],

"color": "red-500",

"domain": "weeklymotion",

"environments": [{"name": "production",\
\
"status": "down"\
\
},\
\
{"name": "sandbox",\
\
"status": "down"\
\
}\
\
],

"icon_logo_url": "https://...",

"inline_logo_url": "https://...",

"inserted_at": "2023-05-04T07:16:56",

"locale": "en-US",

"name": "Weeklymotion",

"status": {"errors": [ ],

"estimated_time_to_complete_in_seconds": null,

"progress_in_percentage": null,

"state": "pending"

},

"timezone": "Coordinated Universal Time (UTC)",

"updated_at": "2023-05-04T07:16:56"

}

}`

## [tag/Organizations/operation/list-organizations](/content/documentation/api/\#tag/Organizations/operation/list-organizations/index.html) List all Organizations

Returns a list of your [Organizations](/content/documentation/api/#the-organization-type/index.html). The [Organizations](/content/documentation/api/#the-organization-type/index.html) 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](/content/documentation/api/#the-organization-type/index.html). Each entry in the array represents a separate [Organization](/content/documentation/api/#the-organization-type/index.html) type. If no [Organizations](/content/documentation/api/#the-organization-type/index.html) are available, the resulting array will be empty. This request should never return an error.

##### query Parameters

|     |     |
| --- | --- |
| page | integer<br>Example: page=1<br>Precise the page of your listing. |
| per\_page | integer<br>Example: per\_page=8<br>Precise the size of the pages of the pagination of the list. |
| q\[environments\_status\_in\]\[\] | string<br>Example: q\[environments\_status\_in\]\[\]=up<br>Filter organizations by functional or non-functional environments. |

### Responses

**200**

OK

get/api/v2/organizations

https://${{cryptr\_service\_url}}/api/v2/organizations

### Request samples

- cURL

Copy

```
curl '${cryptr_service_url}/api/v2/organizations' \
  -d "page=${page}" \
  -d "per_page=${per_page}" \
  -d "q[environments_status_in][]=up"
```

### Response samples

- 200

Content type

application/json

Copy
Expand all  Collapse all

`{"__type__": "List",

"data": [{"__type__": "Organization",\
\
"allowed_email_domains": [ ],\
\
"color": "red-500",\
\
"domain": "actalab-corp-prod",\
\
"environments": [{"name": "production",\
\
"status": "up"\
\
},\
\
{"name": "sandbox",\
\
"status": "up"\
\
}\
\
],\
\
"icon_logo_url": "https://...",\
\
"inline_logo_url": "https://...",\
\
"inserted_at": "2023-06-08T08:13:54",\
\
"locale": "en-US",\
\
"name": "Actalab Corp Prod",\
\
"status": {"errors": [ ],\
\
"estimated_time_to_complete_in_seconds": null,\
\
"progress_in_percentage": null,\
\
"state": "pending"\
\
},\
\
"timezone": "Coordinated Universal Time (UTC)",\
\
"updated_at": "2023-06-08T08:14:12"\
\
},\
\
{"__type__": "Organization",\
\
"allowed_email_domains": [ ],\
\
"color": "red-500",\
\
"domain": "actalab-corp-prod",\
\
"environments": [{"name": "production",\
\
"status": "up"\
\
},\
\
{"name": "sandbox",\
\
"status": "up"\
\
}\
\
],\
\
"icon_logo_url": "https://...",\
\
"inline_logo_url": "https://...",\
\
"inserted_at": "2023-06-08T08:13:54",\
\
"locale": "en-US",\
\
"name": "Actalab Corp Prod",\
\
"status": {"errors": [ ],\
\
"estimated_time_to_complete_in_seconds": null,\
\
"progress_in_percentage": null,\
\
"state": "pending"\
\
},\
\
"timezone": "Coordinated Universal Time (UTC)",\
\
"updated_at": "2023-06-08T08:14:12"\
\
},\
\
{"__type__": "Organization",\
\
"allowed_email_domains": [ ],\
\
"color": "red-500",\
\
"domain": "tutux-corp-sandbox",\
\
"environments": [{"name": "production",\
\
"status": "down"\
\
},\
\
{"name": "sandbox",\
\
"status": "up"\
\
}\
\
],\
\
"icon_logo_url": "https://...",\
\
"inline_logo_url": "https://...",\
\
"inserted_at": "2023-06-08T08:08:53",\
\
"locale": "en-US",\
\
"name": "Tutux Corp Sandbox",\
\
"status": {"errors": [ ],\
\
"estimated_time_to_complete_in_seconds": null,\
\
"progress_in_percentage": null,\
\
"state": "pending"\
\
},\
\
"timezone": "Coordinated Universal Time (UTC)",\
\
"updated_at": "2023-06-08T08:09:10"\
\
},\
\
{"__type__": "Organization",\
\
"allowed_email_domains": [ ],\
\
"color": "red-500",\
\
"domain": "tutux-corp-sandbox",\
\
"environments": [{"name": "production",\
\
"status": "down"\
\
},\
\
{"name": "sandbox",\
\
"status": "up"\
\
}\
\
],\
\
"icon_logo_url": "https://...",\
\
"inline_logo_url": "https://...",\
\
"inserted_at": "2023-06-08T08:08:53",\
\
"locale": "en-US",\
\
"name": "Tutux Corp Sandbox",\
\
"status": {"errors": [ ],\
\
"estimated_time_to_complete_in_seconds": null,\
\
"progress_in_percentage": null,\
\
"state": "pending"\
\
},\
\
"timezone": "Coordinated Universal Time (UTC)",\
\
"updated_at": "2023-06-08T08:09:10"\
\
}\
\
],

"pagination": {"current_page": 1,

"current_pages": [1\
\
],

"next_page": null,

"per_page": 8,

"prev_page": null,

"total_pages": 1

},

"total": 4

}`

## [tag/Organizations/operation/retrieve-organization](/content/documentation/api/\#tag/Organizations/operation/retrieve-organization/index.html) Retrieve an Organization

Fetch an [Organization](/content/documentation/api/#the-organization-type/index.html) 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](/content/documentation/api/#the-organization-type/index.html) for a valid identifier. If the identifier corresponds to a deleted [Organization](/content/documentation/api/#the-organization-type/index.html), a subset of its information is returned, including a 'deleted' property set to true.

##### path Parameters

### Responses

**200**

OK

**401**

Unauthorized

get/api/v2/organizations/{org\_domain}

https://${{cryptr\_service\_url}}/api/v2/organizations/{org\_domain}

### Request samples

- cURL

Copy

```
curl '${cryptr_service_url}/api/v2/organizations/${org_domain}'
```

### Response samples

- 200
- 401

Content type

application/json

Copy
Expand all  Collapse all

`{"__type__": "Organization",

"allowed_email_domains": ["weeklymotion.com"\
\
],

"color": "red-500",

"domain": "weeklymotion",

"environments": [{"name": "production",\
\
"status": "down"\
\
},\
\
{"name": "sandbox",\
\
"status": "down"\
\
}\
\
],

"icon_logo_url": "https://...",

"inline_logo_url": "https://...",

"inserted_at": "2023-05-04T07:16:56",

"locale": "en-US",

"name": "Weeklymotion",

"status": {"errors": [ ],

"estimated_time_to_complete_in_seconds": null,

"progress_in_percentage": null,

"state": "pending"

},

"timezone": "Coordinated Universal Time (UTC)",

"updated_at": "2023-05-04T07:16:56"

}`

## [tag/Organizations/operation/update-organization](/content/documentation/api/\#tag/Organizations/operation/update-organization/index.html) 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](/content/documentation/api/#the-organization-type/index.html) 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

##### query Parameters

|     |     |
| --- | --- |
| name | string<br>Example: name=Weeklymotion<br>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<br>Example: allowed\_email\_domains\[\]=weeklymotion.com<br>List of email domains from the professional emails of the users |

### Responses

**200**

OK

**401**

Unauthorized

**422**

Unprocessable Entity

put/api/v2/organizations/{org\_domain}

https://${{cryptr\_service\_url}}/api/v2/organizations/{org\_domain}

### Request samples

- cURL

Copy

```
curl -X PUT
  '${cryptr_service_url}/api/v2/organizations/${org_domain}'
```

### Response samples

- 200
- 401
- 422

Content type

application/json

Copy
Expand all  Collapse all

`{"__type__": "Organization",

"allowed_email_domains": ["weeklymotion.com"\
\
],

"color": "red-500",

"domain": "weeklymotion",

"environments": [{"name": "production",\
\
"status": "down"\
\
},\
\
{"name": "sandbox",\
\
"status": "down"\
\
}\
\
],

"icon_logo_url": "https://...",

"inline_logo_url": "https://...",

"inserted_at": "2023-05-04T07:16:56",

"locale": "en-US",

"name": "Weeklymotion",

"status": {"errors": [ ],

"estimated_time_to_complete_in_seconds": null,

"progress_in_percentage": null,

"state": "pending"

},

"timezone": "Coordinated Universal Time (UTC)",

"updated_at": "2023-05-04T07:16:56"

}`

## [tag/Users](/content/documentation/api/\#tag/Users/index.html) 👩‍💻 Users

Cryptr stores user profiles for your application in a dedicated hosted cloud database for a specific [Organization](/content/documentation/api/#the-organization-type/index.html). User profile information can come from your users directly. The sources are magic link signup, SSO (via SAML) logins, or Active Directory.

- A ( [User](/content/documentation/api/#the-user-type/index.html)) 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](https://pricing.cryptr.tech/) for more details.

### The User’s Organization domain

Each end user is stored in a distinct directory specific to a dedicated customer ( [Organization](/content/documentation/api/#the-user-type/index.html)). You can determine the domain of the user’s [Organization](/content/documentation/api/#the-user-type/index.html) 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<br>The domain is a **string** value in **lowercase** with **dashes**, generated from the organization’s name. |
| \_\_environment\_\_ | string<br>The environment in which the user is stored, either sandbox (for the test environment) or production. |
| \_\_type\_\_ | string<br>Data type |
| active | boolean<br>Boolean that indicates if the user is considered active or not. |
| address | object (Address) <br>User’s postal address. The value of the address member is of type `Address`, as defined here. |
| email | string <email> <br>Email |
| email\_verified | boolean<br>Boolean that indicates if the email has been verified. |
| id | uuid<br>The immutable identifier. |
| identities | Array of objects (Identity) <br>User's identities |
| inserted\_at | string <date-time> <br>Insertion datetime. |
| metadata | Array of arrays<br>User’s metadata. See [Token > Create a User Metakey](/content/documentation/api/#tag/Token/index.html) |
| phone\_number | string<br>User’s telephone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. |
| phone\_number\_verified | boolean<br>Boolean that indicates whether the phone number has been verified. |
| phone\_numbers | Array of objects (PhoneNumber) <br>User's phone numbers |
| profile | object (Profile) <br>The [OpenID Connect profile](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) specification defines a set of standard Claims. They can be requested to be returned either in the [UserInfo Response](/content/documentation/api/#tag/Users/index.html) or in the [ID Token](/content/documentation/api/#tag/Users/index.html). |
| updated\_at | string <date-time> <br>Update timestamp |

Copy
Expand all  Collapse all

`{"__domain__": "loirama",

"__environment__": "sandbox",

"__type__": "User",

"active": true,

"address": {"country": "FR",

"formatted": "165 avenue de Bretagne\n59000 Lille, France",

"locality": "Lille",

"postal_code": "59000",

"region": "Nord",

"street_address": "165 avenue de Bretagne"

},

"email": "lyla@loirama.co",

"email_verified": false,

"id": "d6a46443-c7bc-4259-aa5d-ce51cc548b57",

"identities": [ ],

"inserted_at": "2023-05-10T13:50:35",

"meta_data": [ ],

"phone_number": "+33 1 23 45 67 89",

"phone_number_verified": false,

"phone_numbers": [ ],

"profile": {"birthdate": "1992-03-10",

"family_name": "Bloggs",

"gender": "female",

"given_name": "Lyla",

"locale": "fr",

"nickname": "lylaB",

"picture": "https://www.cryptr.co",

"preferred_username": null,

"website": "http://www.example.com",

"zoneinfo": "France/Lille"

},

"updated_at": "2023-05-10T13:50:35"

}`

### The Profile type

|     |     |
| --- | --- |
| birthdate | string<br>User’s birthday represented in ISO 8601:2004 \[ISO8601-2004\] YYYY-MM-DD format. |
| family\_name | string<br>The last name is an [OpenID Connect profile](https://en.wikipedia.org/wiki/OpenID) attribute. |
| gender | enum<br>It’s an [OpenID Connect profile](https://en.wikipedia.org/wiki/OpenID) attribute. |
| given\_name | string<br>The first name is an [OpenID Connect profile](https://en.wikipedia.org/wiki/OpenID) attribute. |
| locale | enum<br>It’s an [OpenID Connect profile](https://en.wikipedia.org/wiki/OpenID) attribute. |
| nickname | string<br>It’s an [OpenID Connect profile](https://en.wikipedia.org/wiki/OpenID) attribute. |
| picture | url<br>It’s an [OpenID Connect profile](https://en.wikipedia.org/wiki/OpenID) attribute. |
| preferred\_username | string or null<br>It’s an [OpenID Connect profile](https://en.wikipedia.org/wiki/OpenID) attribute. |
| website | url<br>It’s an [OpenID Connect profile](https://en.wikipedia.org/wiki/OpenID) attribute. |
| zoneinfo | enum<br>It’s an [OpenID Connect profile](https://en.wikipedia.org/wiki/OpenID) attribute. |

Copy

`{"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<br>Country name component. |
| formatted | string<br>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<br>City or locality component. |
| postal\_code | string<br>Zip code or postal code component of the [User](/content/documentation/api/#tag/Users/index.html). |
| region | string<br>State, province, prefecture, or region component of the [User](/content/documentation/api/#tag/Users/index.html). |
| street\_address | string<br>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"). |

Copy

`{"country": "FR",

"formatted": "165 avenue de Bretagne\n59000 Lille, France",

"locality": "Lille",

"postal_code": "59000",

"region": "Nord",

"street_address": "165 avenue de Bretagne"

}`

## [tag/Users/operation/add-user-metadata](/content/documentation/api/\#tag/Users/operation/add-user-metadata/index.html) Add User Metadata

You can add a metadata key, which you have previously created using the [Metakey](/content/documentation/api#tag/Token/operation/create-user-metakey/index.html) 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<br>required | string<br>Example: loirama<br>The domain is a **string** value in **lowercase** with **dashes**, generated from the organization’s name. |
| user\_id<br>required | string<br>Example: 4061e243-b452-4fe4-b9f7-7cb8ec39ce95<br>The ID of the User for which you want to add Metadata |

##### query Parameters

|     |     |
| --- | --- |
| key<br>required | string<br>Example: key=uid<br>The key of the value you want to add to your User. |
| value<br>required | string<br>Example: value=2fa42937<br>The value you want to add to your User, stored in a custom key. |

### Responses

**200**

OK

**401**

Unauthorized

**404**

Not Found

put/api/v2/org/{org\_domain}/users/{id}/add-metadata

https://${{cryptr\_service\_url}}/api/v2/org/{org\_domain}/users/{id}/add-metadata

### Request samples

- cURL

Copy

```
curl -X PUT '${cryptr_service_url}/api/v2/org/:org_domain/users/:user_id/add-metadata' \
  -d key='uid' \
  -d value='2fa42937'
```

### Response samples

- 200
- 401
- 404

Content type

application/json

Copy
Expand all  Collapse all

`{"__domain__": "loirama",

"__environment__": "sandbox",

"__type__": "User",

"active": true,

"address": {"country": "FR",

"formatted": "165 avenue de Bretagne\n59000 Lille, France",

"locality": "Lille",

"postal_code": "59000",

"region": "Nord",

"street_address": "165 avenue de Bretagne"

},

"email": "lyla@loirama.co",

"email_verified": false,

"id": "d6a46443-c7bc-4259-aa5d-ce51cc548b57",

"identities": [ ],

"inserted_at": "2023-05-10T13:50:35",

"meta_data": [ ],

"phone_number": "+33 1 23 45 67 89",

"phone_number_verified": false,

"phone_numbers": [ ],

"profile": {"birthdate": "1992-03-10",

"family_name": "Bloggs",

"gender": "female",

"given_name": "Lyla",

"locale": "fr",

"nickname": "lylaB",

"picture": "https://www.cryptr.co",

"preferred_username": null,

"website": "http://www.example.com",

"zoneinfo": "France/Lille"

},

"updated_at": "2023-05-10T13:50:35"

}`

## [tag/Users/operation/create-user](/content/documentation/api/\#tag/Users/operation/create-user/index.html) Create a User

Creates a new **User** in an [Organization](/content/documentation/api/#the-organization-type/index.html).

#### RETURNS

Returns a [User](/content/documentation/api/#tag/Users/index.html) attached to an [Organization](/content/documentation/api/#the-organization-type/index.html) 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<br>required | string<br>Example: loirama<br>The domain is a **string** value in **lowercase** with **dashes**, generated from the organization’s name. |

##### query Parameters

|     |     |
| --- | --- |
| address | object (Address) <br>Example: country=FR&formatted=165 avenue de Bretagne<br>59000 Lille, France&locality=Lille&postal\_code=59000&region=Nord&street\_address=165 avenue de Bretagne<br>User’s postal address. The value of the address member is an [Address](/content/documentation/api/#the-address-type/index.html) type defined [here](/content/documentation/api/#the-address-type/index.html). |
| email<br>required | string<br>Example: email=lyla@loirama.co<br>Email is a required field as it is part of the security for the created end-user account. |
| phone\_number | string<br>Example: phone\_number=+33123456789<br>User telephone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. |
| profile | object (Profile) <br>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<br>The [OpenID Connect profile](https://en.wikipedia.org/wiki/OpenID) 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

**201**

Created

**422**

Unprocessable Entity

post/api/v2/org/{org\_domain}/users

https://${{cryptr\_service\_url}}/api/v2/org/{org\_domain}/users

### Request samples

- cURL

Copy

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

- 201
- 422

Content type

application/json

Copy
Expand all  Collapse all

`{"__domain__": "loirama",

"__environment__": "sandbox",

"__type__": "User",

"active": true,

"address": {"country": "FR",

"formatted": "165 avenue de Bretagne\n59000 Lille, France",

"locality": "Lille",

"postal_code": "59000",

"region": "Nord",

"street_address": "165 avenue de Bretagne"

},

"email": "lyla@loirama.co",

"email_verified": false,

"id": "d6a46443-c7bc-4259-aa5d-ce51cc548b57",

"identities": [ ],

"inserted_at": "2023-05-10T13:50:35",

"meta_data": [ ],

"phone_number": "+33 1 23 45 67 89",

"phone_number_verified": false,

"phone_numbers": [ ],

"profile": {"birthdate": "1992-03-10",

"family_name": "Bloggs",

"gender": "female",

"given_name": "Lyla",

"locale": "fr",

"nickname": "lylaB",

"picture": "https://www.cryptr.co",

"preferred_username": null,

"website": "http://www.example.com",

"zoneinfo": "France/Lille"

},

"updated_at": "2023-05-10T13:50:35"

}`

## [tag/Users/operation/delete-user-by-id](/content/documentation/api/\#tag/Users/operation/delete-user-by-id/index.html) Delete a User By ID

Delete an existing user.

#### RETURNS

Returns a deleted [User](/content/documentation/api/#tag/Users/index.html) from an [Organization](/content/documentation/api/#the-organization-type/index.html).

##### path Parameters

|     |     |
| --- | --- |
| org\_domain<br>required | string<br>Example: b-oreal<br>The domain is a **string** value in **lowercase** with **dashes**, generated from the organization’s name. |
| user\_id<br>required | uuid<br>Example: 796ffbba-1698-4b64-b667-5e5006fb52d2<br>The immutable identifier. |

### Responses

**200**

OK

**401**

Unauthorized

delete/api/v2/org/{org\_domain}/users/{id}

https://${{cryptr\_service\_url}}/api/v2/org/{org\_domain}/users/{id}

### Request samples

- cURL

Copy

```
curl -X DELETE '${cryptr_service_url}/api/v2/org/${org_domain}/users/${user_id}'
```

### Response samples

- 200
- 401

Content type

application/json

Copy
Expand all  Collapse all

`{"deleted": true,

"resource": {"__domain__": "b-oreal",

"__environment__": "sandbox",

"__type__": "User",

"active": true,

"address": {"country": "FR",

"formatted": "165 avenue de Bretagne\n59000 Lille, France",

"locality": "Lille",

"postal_code": "59000",

"region": "Nord",

"street_address": "165 avenue de Bretagne"

},

"email": "karim@b-oreal.co",

"email_verified": false,

"id": "796ffbba-1698-4b64-b667-5e5006fb52d2",

"identities": [ ],

"inserted_at": "2023-05-04T13:23:32",

"meta_data": [ ],

"phone_number": null,

"phone_number_verified": false,

"phone_numbers": [ ],

"profile": {"birthdate": "1992-03-10",

"family_name": "Guerra",

"gender": "male",

"given_name": "Karim",

"locale": "fr",

"nickname": "kGuerra",

"picture": "https://www.cryptr.co",

"preferred_username": null,

"website": "http://www.example.com",

"zoneinfo": "France/Lille"

},

"updated_at": "2023-05-04T13:23:32"

}

}`

## [tag/Users/operation/list-users](/content/documentation/api/\#tag/Users/operation/list-users/index.html) List all Users

Returns a list of your [users](/content/documentation/api/#the-user-type/index.html), 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](/content/documentation/api/#the-user-type/index.html).
Each entry in the array represents a separate [user](/content/documentation/api/#the-user-type/index.html) type.
If no [users](/content/documentation/api/#the-user-type/index.html) are available, the resulting array will be empty. This request should never return an error.

##### path Parameters

##### query Parameters

|     |     |
| --- | --- |
| page | integer<br>Example: page=1<br>Precise the page of your listing. |
| per\_page | integer<br>Example: per\_page=8<br>Precise the size of the pages of the pagination of the list. |

### Responses

**200**

OK

**401**

Unauthorized

get/api/v2/org/{org\_domain}/users

https://${{cryptr\_service\_url}}/api/v2/org/{org\_domain}/users

### Request samples

- cURL

Copy

```
curl "${cryptr_service_url}/api/v2/org/${org_domain}/users" \
  -d page=${page}
  -d per_page=${per_page}
```

### Response samples

- 200
- 401

Content type

application/json

Copy
Expand all  Collapse all

`{"__type__": "List",

"data": [{"__domain__": "b-oreal",\
\
"__environment__": "sandbox",\
\
"__type__": "User",\
\
"active": true,\
\
"address": {"country": "FR",\
\
"formatted": "165 avenue de Bretagne\n59000 Lille, France",\
\
"locality": "Lille",\
\
"postal_code": "59000",\
\
"region": "Nord",\
\
"street_address": "165 avenue de Bretagne"\
\
},\
\
"email": "audrey@b-oreal.co",\
\
"email_verified": false,\
\
"id": "9aaf8fb9-89b8-488d-a5bc-dd61b7e63f2e",\
\
"identities": [ ],\
\
"inserted_at": "2023-05-04T13:24:49",\
\
"meta_data": [ ],\
\
"phone_number": null,\
\
"phone_number_verified": false,\
\
"phone_numbers": [ ],\
\
"profile": {"birthdate": "1992-03-10",\
\
"family_name": "Gallagher",\
\
"gender": "female",\
\
"given_name": "Audrey",\
\
"locale": "fr",\
\
"nickname": "aGallagher",\
\
"picture": "https://www.cryptr.co",\
\
"preferred_username": null,\
\
"website": "http://www.example.com",\
\
"zoneinfo": "France/Lille"\
\
},\
\
"updated_at": "2023-05-04T13:24:49"\
\
},\
\
{"__domain__": "b-oreal",\
\
"__environment__": "sandbox",\
\
"__type__": "User",\
\
"active": true,\
\
"address": {"country": "FR",\
\
"formatted": "165 avenue de Bretagne\n59000 Lille, France",\
\
"locality": "Lille",\
\
"postal_code": "59000",\
\
"region": "Nord",\
\
"street_address": "165 avenue de Bretagne"\
\
},\
\
"email": "karim@b-oreal.co",\
\
"email_verified": false,\
\
"id": "796ffbba-1698-4b64-b667-5e5006fb52d2",\
\
"identities": [ ],\
\
"inserted_at": "2023-05-04T13:23:32",\
\
"meta_data": [ ],\
\
"phone_number": null,\
\
"phone_number_verified": false,\
\
"phone_numbers": [ ],\
\
"profile": {"birthdate": "1992-03-10",\
\
"family_name": "Guerra",\
\
"gender": "male",\
\
"given_name": "Karim",\
\
"locale": "fr",\
\
"nickname": "kGuerra",\
\
"picture": "https://www.cryptr.co",\
\
"preferred_username": null,\
\
"website": "http://www.example.com",\
\
"zoneinfo": "France/Lille"\
\
},\
\
"updated_at": "2023-05-04T13:23:32"\
\
}\
\
],

"pagination": {"current_page": 1,

"current_pages": [1,\
\
2\
\
],

"next_page": 2,

"per_page": 2,

"prev_page": null,

"total_pages": 2

},

"total": 3

}`

## [tag/Users/operation/remove-user-metadata](/content/documentation/api/\#tag/Users/operation/remove-user-metadata/index.html) 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

##### query Parameters

|     |     |
| --- | --- |
| key<br>required | string<br>Example: key=uid<br>The key of the value you want to remove from your User. |

### Responses

**200**

OK

**401**

Unauthorized

**404**

Not Found

put/api/v2/org/{org\_domain}/users/{id}/remove-metadata

https://${{cryptr\_service\_url}}/api/v2/org/{org\_domain}/users/{id}/remove-metadata

### Request samples

- cURL

Copy

```
curl -X PUT '${cryptr_service_url}/api/v2/org/:org_domain/users/:user_id/remove-metadata' \
  -d key='uid'
```

### Response samples

- 200
- 401
- 404

Content type

application/json

Copy
Expand all  Collapse all

`{"__domain__": "loirama",

"__environment__": "sandbox",

"__type__": "User",

"address": {"country": "FR",

"formatted": "165 avenue de Bretagne\n59000 Lille, France",

"locality": "Lille",

"postal_code": "59000",

"region": "Nord",

"street_address": "165 avenue de Bretagne"

},

"email": "lyla@loirama.co",

"email_verified": false,

"id": "d6a46443-c7bc-4259-aa5d-ce51cc548b57",

"inserted_at": "2023-05-10T13:50:35",

"meta_data": [{"key": {"name": "uid",\
\
"required": false,\
\
"type": "string"\
\
}\
\
}\
\
],

"phone_number": "+33 1 23 45 67 89",

"phone_number_verified": false,

"profile": {"birthdate": "1992-03-10",

"family_name": "Bloggs",

"gender": "female",

"given_name": "Lyla",

"locale": "fr",

"nickname": "lylaB",

"picture": "https://www.cryptr.co",

"preferred_username": null,

"website": "http://www.example.com",

"zoneinfo": "France/Lille"

},

"updated_at": "2023-05-10T13:50:35"

}`

## [tag/Users/operation/retrieve-user-by-email-or-id](/content/documentation/api/\#tag/Users/operation/retrieve-user-by-email-or-id/index.html) Retrieve a User By Email or ID

Fetch a [User](/content/documentation/api/#the-user-type/index.html) by their email or id.

#### RETURNS

Returns a [User](/content/documentation/api/#the-user-type/index.html) for a valid email or identifier. If the [User](/content/documentation/api/#the-user-type/index.html) has been deleted, a subset of their information is returned, including a **deleted** property set to true.

##### path Parameters

|     |     |
| --- | --- |
| org\_domain<br>required | string<br>Example: loirama<br>The domain is a **string** value in **lowercase** with **dashes**, generated from the organization’s name. |
| email\_or\_id<br>required | string<br>Example: janis.joplin@example.com or 86561a93-bee2-4eba-96ff-6769d617eaf8<br>The user’s email or their UUID (user identifier). |

### Responses

**200**

OK

**401**

Unauthorized

get/api/v2/org/{org\_domain}/users/{email\_or\_id}

https://${{cryptr\_service\_url}}/api/v2/org/{org\_domain}/users/{email\_or\_id}

### Request samples

- cURL

Copy

```
curl '${cryptr_service_url}/api/v2/org/${org_domain}/users/${user_id}'
```

### Response samples

- 200
- 401

Content type

application/json

Copy
Expand all  Collapse all

`{"__domain__": "loirama",

"__environment__": "sandbox",

"__type__": "User",

"active": true,

"address": {"country": "FR",

"formatted": "165 avenue de Bretagne\n59000 Lille, France",

"locality": "Lille",

"postal_code": "59000",

"region": "Nord",

"street_address": "165 avenue de Bretagne"

},

"email": "lyla@loirama.co",

"email_verified": false,

"id": "d6a46443-c7bc-4259-aa5d-ce51cc548b57",

"identities": [ ],

"inserted_at": "2023-05-10T13:50:35",

"meta_data": [ ],

"phone_number": "+33 1 23 45 67 89",

"phone_number_verified": false,

"phone_numbers": [ ],

"profile": {"birthdate": "1992-03-10",

"family_name": "Bloggs",

"gender": "female",

"given_name": "Lyla",

"locale": "fr",

"nickname": "lylaB",

"picture": "https://www.cryptr.co",

"preferred_username": null,

"website": "http://www.example.com",

"zoneinfo": "France/Lille"

},

"updated_at": "2023-05-10T13:50:35"

}`

## [tag/Users/operation/update-user](/content/documentation/api/\#tag/Users/operation/update-user/index.html) Update a User

Update an existing user.

#### RETURNS

Returns an updated [Users](/content/documentation/api/#tag/Users/index.html) from an [Organization](/content/documentation/api/#the-organization-type/index.html) 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<br>required | string<br>Example: loirama<br>The domain is a **string** value in **lowercase** with **dashes**, generated from the organization’s name. |
| user\_id<br>required | uuid<br>Example: 8724da20-c140-4d01-82d2-bc87079a6f6e<br>The immutable identifier. |

##### query Parameters

### Responses

**200**

OK

**401**

Unauthorized

**422**

Unprocessable Entity

put/api/v2/org/{org\_domain}/users/{id}

https://${{cryptr\_service\_url}}/api/v2/org/{org\_domain}/users/{id}

### Request samples

- cURL

Copy

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

- 200
- 401
- 422

Content type

application/json

Copy
Expand all  Collapse all

`{"__domain__": "loirama",

"__environment__": "sandbox",

"__type__": "User",

"active": true,

"address": {"country": "FR",

"formatted": "165 avenue de Bretagne\n59000 Lille, France",

"locality": "Lille",

"postal_code": "59000",

"region": "Nord",

"street_address": "165 avenue de Bretagne"

},

"email": "lyla@loirama.co",

"email_verified": false,

"id": "d6a46443-c7bc-4259-aa5d-ce51cc548b57",

"identities": [ ],

"inserted_at": "2023-05-10T13:50:35",

"meta_data": [ ],

"phone_number": "+33 1 23 45 67 89",

"phone_number_verified": false,

"phone_numbers": [ ],

"profile": {"birthdate": "1992-03-10",

"family_name": "Bloggs",

"gender": "female",

"given_name": "Lyla",

"locale": "fr",

"nickname": "lylaB",

"picture": "https://www.cryptr.co",

"preferred_username": null,

"website": "http://www.example.com",

"zoneinfo": "France/Lille"

},

"updated_at": "2023-05-10T13:50:35"

}`

## [tag/Directory-Syncs](/content/documentation/api/\#tag/Directory-Syncs/index.html) 🔄 Directory Syncs

The term [Directory Sync](/content/documentation/api/#the-directory-sync-type/index.html) 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<br>Immutable identifier of the organization in a ' **slug** format': domain is a **string** value in lowercase with underscores, generated from the name. |
| \_\_environment\_\_ | string<br>The environment in which the user is stored, either sandbox (for the test environment) or production. |
| \_\_type\_\_ | string<br>The `__type__` is a **string** that lets you differentiate data types. |
| active | boolean<br>Boolean that indicates if a Directory Sync is active |
| auth\_secret\_token | object (AuthSecretToken) <br>Use the value as a Bearer token for your SCIM implementation in your provider.<br>💡 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<br>A unique **string** that identifies a directory sync. |
| inserted\_at | string <date-time> <br>Date time of the insertion. |
| provider\_type | string<br>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> <br>Update timestamp |

Copy
Expand all  Collapse all

`{"__domain__": "barker-inc",

"__environment__": "sandbox",

"__type__": "DirectorySync",

"active": true,

"auth_secret_token": {"hint": "You must save this value. If you lose it you will have to create a new one using the reset endpoint.",

"provider_key": "OAuth Bearer Token",

"value": "barker-inc.sandbox.48789cb6-33c3-47fe-bb92-8774cda6d327.CrVrhHZuQfVgGuKkYY7lvBMgsqRU15flunxYOrOhPfGg6IW6wDA2ic41MRMQfge0O_kBXRjLbI4HqFaxBfTdqtbzmGTiFbRZmoIgjjeuqBwROiDprKUQqVAjad3CXjd8"

},

"id": "32dad740-142e-4af3-ac69-de5f36915d80",

"inserted_at": "2023-06-15T09:23:55",

"provider_type": null,

"updated_at": "2023-06-15T09:23:55"

}`

## [tag/Directory-Syncs/operation/create-directory-sync](/content/documentation/api/\#tag/Directory-Syncs/operation/create-directory-sync/index.html) 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<br>required | string<br>Example: barker-inc<br>The domain is a **string** value in **lowercase** with **dashes**, generated from the organization’s name. |

### Responses

**201**

Created

**401**

Unauthorized

**409**

Conflict

post/api/v2/org/{org\_domain}/directory-sync

https://${{cryptr\_service\_url}}/api/v2/org/{org\_domain}/directory-sync

### Request samples

- cURL

Copy

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

### Response samples

- 201
- 401
- 409

Content type

application/json

Copy
Expand all  Collapse all

`{"__domain__": "barker-inc",

"__environment__": "sandbox",

"__type__": "DirectorySync",

"active": true,

"auth_secret_token": {"hint": "You must save this value. If you lose it you will have to create a new one using the reset endpoint.",

"provider_key": "OAuth Bearer Token",

},

"id": "32dad740-142e-4af3-ac69-de5f36915d80",

"inserted_at": "2023-06-15T09:23:55",

"provider_type": null,

"updated_at": "2023-06-15T09:23:55"

}`

## [tag/Directory-Syncs/operation/retrieve-directory-sync](/content/documentation/api/\#tag/Directory-Syncs/operation/retrieve-directory-sync/index.html) Retrieve a Directory Sync

Fetch a [Directory Sync](/content/documentation/api/#the-directory-sync-type/index.html) 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](/content/documentation/api/#the-directory-sync-type/index.html) for a valid organization/environment pair. If the [Directory Sync](/content/documentation/api/#the-directory-sync-type/index.html) has been deleted, a **NoResult** response is returned.

##### path Parameters

|     |     |
| --- | --- |
| org\_domain<br>required | string<br>Example: misapret<br>The domain is a **string** value in **lowercase** with **dashes**, generated from the organization’s name. |

### Responses

**200**

OK

get/api/v2/org/{org\_domain}/directory-sync

https://${{cryptr\_service\_url}}/api/v2/org/{org\_domain}/directory-sync

### Request samples

- cURL

Copy

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

### Response samples

- 200

Content type

application/json

Copy
Expand all  Collapse all

`{"__domain__": "barker-inc",

"__environment__": "sandbox",

"__type__": "DirectorySync",

"active": true,

"auth_secret_token": {"hint": "This value is only displayed once at creation. If you have lost this value and wish to recover it, please consider using the reset endpoint.",

"provider_key": "OAuth Access Token",

"value": "hidden"

},

"id": "32dad740-142e-4af3-ac69-de5f36915d80",

"inserted_at": "2023-06-15T09:23:55",

"provider_type": null,

"updated_at": "2023-06-15T12:11:17"

}`

## [tag/Directory-Syncs/operation/update-directory-sync](/content/documentation/api/\#tag/Directory-Syncs/operation/update-directory-sync/index.html) 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](/content/documentation/api/#the-directory-sync-type/index.html) for a valid organization/environment pair. If the [Directory Sync](/content/documentation/api/#the-directory-sync-type/index.html) has been deleted, a **NoResult** response is returned.

##### path Parameters

##### query Parameters

|     |     |
| --- | --- |
| active<br>required | boolean<br>Example: active=true<br>Boolean that indicates if a Directory Sync is active |

### Responses

**200**

OK

**401**

Unauthorized

put/api/v2/org/{org\_domain}/directory-sync

https://${{cryptr\_service\_url}}/api/v2/org/{org\_domain}/directory-sync

### Request samples

- cURL

Copy

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

### Response samples

- 200
- 401

Content type

application/json

Copy
Expand all  Collapse all

`{"__domain__": "barker-inc",

"__environment__": "sandbox",

"__type__": "DirectorySync",

"active": true,

"auth_secret_token": {"hint": "You must save this value. If you lose it you will have to create a new one using the reset endpoint.",

"provider_key": "OAuth Bearer Token",

},

"id": "32dad740-142e-4af3-ac69-de5f36915d80",

"inserted_at": "2023-06-15T09:23:55",

"provider_type": null,

"updated_at": "2023-06-15T09:23:55"

}`

## [tag/SSO](/content/documentation/api/\#tag/SSO/index.html) 🔌 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](/content/documentation/api/#the-sso-connection-type/index.html)) 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](https://pricing.cryptr.tech/) for more details.

|     |     |
| --- | --- |
| \_\_type\_\_ | string<br>The `__type__` is a **string** that lets you differentiate data types. |
| active | boolean<br>Default: true<br>Specify if the connection is usable. |
| id | string<br>Unique identifier of the Identity Provider used in the SAML protocol. |
| inserted\_at | string <date-time> <br>Date time of the insertion |
| number\_users\_provisioning\_limit | integer<br>The limit of simultaneously possible SSO sessions for the SSO connection. |
| organization | object (Organization) <br>Data of the organization |
| provider\_type | string<br>The provider type (Okta, Google Workspace, ADFS, etc.) of the SSO connection. |
| saml\_config | object (SamlConfig) <br>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<br>The service provider (SP) identifier is a unique code that identifies an application or service within an authentication platform. |
| updated\_at | string <date-time> <br>Update timestamp |
| users\_access\_policy | string<br>Default: "provision\_new\_users"<br>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). |

Copy
Expand all  Collapse all

`{"__type__": "SsoConnection",

"active": true,

"id": "barker_inc_S6f5ndf8mZqfoBKoxEotMV",

"inserted_at": "2023-06-08T13:47:41",

"number_users_provisioning_limit": 99,

"organization": {"__type__": "Organization",

"allowed_email_domains": ["barker.co"\
\
],

"domain": "barker-inc",

"environments": [{"name": "production",\
\
"status": "down"\
\
},\
\
{"name": "sandbox",\
\
"status": "up"\
\
}\
\
],

"inserted_at": "2023-06-08T12:12:28",

"name": "Barker",

"status": {"errors": [ ],

"estimated_time_to_complete_in_seconds": null,

"progress_in_percentage": null,

"state": "pending"

},

"updated_at": "2023-06-08T12:37:59"

},

"provider_type": "saml.azure_ad",

"saml_config": {"acs_url": "https://www.cryptr.co",

"cryptr_metadata_url": "https://www.cryptr.co",

"entity_id": "shark_academy_MgF6Z9maZKriEBbLM9KZJj",

"slo_response_url": "https://www.cryptr.co",

"slo_url": "https://www.cryptr.co",

"sso_provider_metadata": null

},

"sp_id": "shark_academy_MgF6Z9maZKriEBbLM9KZJj",

"updated_at": "2023-06-08T13:47:41",

"users_access_policy": "provision_new_users"

}`

> Before you can create an SSO challenge, you must first set up an [SSO connection](/content/documentation/api/api#tag/SSO-Connections/operation/create-sso-connection/index.html).

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<br>The environment in which the user is stored, either sandbox (for the test environment) or production. |
| \_\_type\_\_ | string<br>The `__type__` is a **string** that lets you differentiate data types. |
| authorization\_url | string<br>URL used to redirect users to a page where they can provide consent during the authentication process. |
| expired\_at | integer<br>The expiration date and time of the SSO challenge |
| redirect\_uri | string<br>URL used to redirect the user after an interaction with a service or application. |
| request\_id | uuid<br>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<br>The unique identifier of the SSO Connection used. |

Copy

`{"__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"

}`

## [tag/SSO/operation/create-sso-challenge (2)](/content/documentation/api/\#tag/SSO/operation/create-sso-challenge%20(2/index.html)) 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<br>required | string<br>Example: redirect\_uri=https://loirama.com/welcome-back-user<br>URL used to redirect the user after an interaction with a service or application. |
| user\_email | string <email> <br>Example: user\_email=it\_sso\_person@sso.client.com<br>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.<br>**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<br>Example: org\_domain=loirama<br>The domain is a **string** value in **lowercase** with **dashes**, generated from the organization’s name.<br>**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

**201**

Created

post/api/v2/sso-saml-challenge

https://${{cryptr\_service\_url}}/api/v2/sso-saml-challenge

### Request samples

- cURL

Copy

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

- 201

Content type

application/json

Copy

`{"__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"

}`

## [tag/SSO/operation/create-sso-connection](/content/documentation/api/\#tag/SSO/operation/create-sso-connection/index.html) Create an SSO Connection

Creates a new SSO connection type. The response automatically expands the `onboarding` nested element.

#### RETURNS

Returns an [SSO Connection](/content/documentation/api/#the-ssoconnection-type/index.html) if the creation succeeds.

##### path Parameters

|     |     |
| --- | --- |
| org\_domain<br>required | string<br>Example: well-agency<br>The domain is a **string** value in **lowercase** with **dashes**, generated from the organization’s name. |

##### query Parameters

|     |     |
| --- | --- |
| number\_users\_provisioning\_limit | integer<br>Change the limit of simultaneously possible SSO sessions for the targeted [SSO Connection](/content/documentation/api/#the-sso-connection-type/index.html)<br>⚠️ Depending on the `users_access_policy` value. |
| users\_access\_policy | string<br>Default: "provision\_new\_users"<br>Enum:"only\_registered\_users""provision\_new\_users""unregistered\_users\_allowed"<br>Example: users\_access\_policy=unregistered\_users\_allowed<br>The `users_access_policy` key determines how users are managed when they log in for the first time via SSO.<br>Possible values for this key are:<br>- `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.<br>- `provision_new_users`: When the user attempts to log in for the first time, the system will automatically create a user for them.<br>- `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<br>Default: true<br>If you want to create it but not activate it for now |

### Responses

**201**

Created

post/api/v2/org/{org\_domain}/sso-connection

https://${{cryptr\_service\_url}}/api/v2/org/{org\_domain}/sso-connection

### Request samples

- cURL

Copy

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

### Response samples

- 201

Content type

application/json

Copy
Expand all  Collapse all

`{"__type__": "SsoConnection",

"active": true,

"id": "barker_inc_S6f5ndf8mZqfoBKoxEotMV",

"inserted_at": "2023-06-08T13:47:41",

"number_users_provisioning_limit": 99,

"organization": {"__type__": "Organization",

"allowed_email_domains": ["barker.co"\
\
],

"domain": "barker-inc",

"environments": [{"name": "production",\
\
"status": "down"\
\
},\
\
{"name": "sandbox",\
\
"status": "up"\
\
}\
\
],

"inserted_at": "2023-06-08T12:12:28",

"name": "Barker",

"status": {"errors": [ ],

"estimated_time_to_complete_in_seconds": null,

"progress_in_percentage": null,

"state": "pending"

},

"updated_at": "2023-06-08T12:37:59"

},

"provider_type": "saml.azure_ad",

"saml_config": {"acs_url": "https://www.cryptr.co",

"cryptr_metadata_url": "https://www.cryptr.co",

"entity_id": "shark_academy_MgF6Z9maZKriEBbLM9KZJj",

"slo_response_url": "https://www.cryptr.co",

"slo_url": "https://www.cryptr.co",

"sso_provider_metadata": null

},

"sp_id": "shark_academy_MgF6Z9maZKriEBbLM9KZJj",

"updated_at": "2023-06-08T13:47:41",

"users_access_policy": "provision_new_users"

}`

## [tag/SSO/operation/list-sso-connections](/content/documentation/api/\#tag/SSO/operation/list-sso-connections/index.html) List all SSO Connections

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

#### RETURNS

Returns list of [SSO Connections](/content/documentation/api/#the-sso-connection-type/index.html) with nested objects if preload\_associations is set, and paginated if related attributes are present.

##### query Parameters

|     |     |
| --- | --- |
| page | integer<br>Example: page=1<br>Specify the page of your listing. |
| per\_page | integer<br>Example: per\_page=2<br>Specify the size of the pages for pagination of the list. |

### Responses

**200**

OK

get/api/v2/sso-connections

https://${{cryptr\_service\_url}}/api/v2/sso-connections

### Request samples

- cURL

Copy

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

```

### Response samples

- 200

Content type

application/json

Copy
Expand all  Collapse all

`{"__type__": "List",

"data": [{"__type__": "SsoConnection",\
\
"id": "barker_inc_ENbw8MukSNtTKCqPZC2U7g",\
\
"inserted_at": "2023-06-09T14:23:09",\
\
"number_users_provisioning_limit": 99,\
\
"organization": {"__type__": "Organization",\
\
"allowed_email_domains": ["barker.co"\
\
],\
\
"domain": "barker-inc",\
\
"environments": [{"name": "production",\
\
"status": "down"\
\
},\
\
{"name": "sandbox",\
\
"status": "up"\
\
}\
\
],\
\
"inserted_at": "2023-06-08T12:12:28",\
\
"name": "Barker",\
\
"status": {"errors": [ ],\
\
"estimated_time_to_complete_in_seconds": null,\
\
"progress_in_percentage": null,\
\
"state": "pending"\
\
},\
\
"updated_at": "2023-06-08T12:37:59"\
\
},\
\
"provider_type": "saml.azure_ad",\
\
"saml_config": {"acs_url": "https://www.cryptr.co",\
\
"cryptr_metadata_url": "https://www.cryptr.co",\
\
"entity_id": "shark_academy_MgF6Z9maZKriEBbLM9KZJj",\
\
"slo_response_url": "https://www.cryptr.co",\
\
"slo_url": "https://www.cryptr.co",\
\
"sso_provider_metadata": null\
\
},\
\
"sp_id": "shark_academy_MgF6Z9maZKriEBbLM9KZJj",\
\
"updated_at": "2023-06-09T14:23:09",\
\
"users_access_policy": "provision_new_users"\
\
},\
\
{"__type__": "SsoConnection",\
\
"id": "looney_tunes_gNT8hCyC7MsovKaLFWnSUh",\
\
"inserted_at": "2023-05-26T07:22:47",\
\
"number_users_provisioning_limit": null,\
\
"organization": {"__type__": "Organization",\
\
"allowed_email_domains": ["Looney_tunes.co"\
\
],\
\
"domain": "looney-tunes",\
\
"environments": [{"name": "sandbox",\
\
"status": "up"\
\
},\
\
{"name": "production",\
\
"status": "up"\
\
}\
\
],\
\
"inserted_at": "2023-05-26T07:21:20",\
\
"name": "Looney tunes",\
\
"status": {"errors": [ ],\
\
"estimated_time_to_complete_in_seconds": null,\
\
"progress_in_percentage": null,\
\
"state": "pending"\
\
},\
\
"updated_at": "2023-05-26T07:21:40"\
\
},\
\
"provider_type": "unset",\
\
"saml_config": {"acs_url": "https://www.cryptr.co",\
\
"cryptr_metadata_url": "https://www.cryptr.co",\
\
"entity_id": "shark_academy_MgF6Z9maZKriEBbLM9KZJj",\
\
"slo_response_url": "https://www.cryptr.co",\
\
"slo_url": "https://www.cryptr.co",\
\
"sso_provider_metadata": null\
\
},\
\
"sp_id": "shark_academy_MgF6Z9maZKriEBbLM9KZJj",\
\
"updated_at": "2023-05-26T07:22:47",\
\
"users_access_policy": "provision_new_users"\
\
}\
\
],

"pagination": {"current_page": 1,

"current_pages": [1,\
\
2,\
\
3,\
\
"...",\
\
26\
\
],

"next_page": 2,

"per_page": 2,

"prev_page": null,

"total_pages": 26

},

"total": 52

}`

## [tag/SSO/operation/retrieve-sso-connection](/content/documentation/api/\#tag/SSO/operation/retrieve-sso-connection/index.html) Retrieve an SSO Connection

Fetch an SSO connection, useful to know its configuration and also fetch nested object `onboarding`.

#### RETURNS

Returns the [SSO Connection](/content/documentation/api/#the-sso-connection-type/index.html)

##### path Parameters

|     |     |
| --- | --- |
| org\_domain<br>required | string<br>Example: lalylala<br>The domain is a **string** value in **lowercase** with **dashes**, generated from the organization’s name. |

### Responses

**200**

OK

get/api/v2/org/{org\_domain}/sso-connection

https://${{cryptr\_service\_url}}/api/v2/org/{org\_domain}/sso-connection

### Request samples

- cURL

Copy

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

### Response samples

- 200

Content type

application/json

Copy
Expand all  Collapse all

`{"__type__": "SsoConnection",

"active": true,

"id": "barker_inc_S6f5ndf8mZqfoBKoxEotMV",

"inserted_at": "2023-06-08T13:47:41",

"number_users_provisioning_limit": 99,

"organization": {"__type__": "Organization",

"allowed_email_domains": ["barker.co"\
\
],

"domain": "barker-inc",

"environments": [{"name": "production",\
\
"status": "down"\
\
},\
\
{"name": "sandbox",\
\
"status": "up"\
\
}\
\
],

"inserted_at": "2023-06-08T12:12:28",

"name": "Barker",

"status": {"errors": [ ],

"estimated_time_to_complete_in_seconds": null,

"progress_in_percentage": null,

"state": "pending"

},

"updated_at": "2023-06-08T12:37:59"

},

"provider_type": "saml.azure_ad",

"saml_config": {"acs_url": "https://www.cryptr.co",

"cryptr_metadata_url": "https://www.cryptr.co",

"entity_id": "shark_academy_MgF6Z9maZKriEBbLM9KZJj",

"slo_response_url": "https://www.cryptr.co",

"slo_url": "https://www.cryptr.co",

"sso_provider_metadata": null

},

"sp_id": "shark_academy_MgF6Z9maZKriEBbLM9KZJj",

"updated_at": "2023-06-08T13:47:41",

"users_access_policy": "provision_new_users"

}`

## [tag/SSO/operation/update-sso-connection](/content/documentation/api/\#tag/SSO/operation/update-sso-connection/index.html) 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](/content/documentation/api/#the-sso-connection-type/index.html)

##### path Parameters

##### query Parameters

|     |     |
| --- | --- |
| active | boolean<br>Example: active=true<br>Change the state of the SSO Connection to enable/disable requests. |
| metadata | string<br>Example: metadata=3d5245f2-194a-498c-ad28-736ca9fffb3b<br>This should be the XML metadata string content.<br>If you want to change the XML for the targeted [Sso Connection](/content/documentation/api/#the-sso-connection-type/index.html).<br>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<br>Change the limit of simultaneously possible SSO sessions for the targeted [SSO Connection](/content/documentation/api/#the-sso-connection-type/index.html)<br>⚠️ Depending on the `users_access_policy` value. |
| users\_access\_policy | string<br>Example: users\_access\_policy=provision\_new\_users<br>Change the rule for end-user session opening for the targeted [SSO Connection](/content/documentation/api/#the-sso-connection-type/index.html) |
| preload\_associations | Array of strings<br>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

**200**

OK

put/api/v2/org/{org\_domain}/sso-connection

https://${{cryptr\_service\_url}}/api/v2/org/{org\_domain}/sso-connection

### Request samples

- cURL

Copy

```
curl -X PUT 'https://${YOUR_CRYPTR_SERVICE_URL}/api/v2/sso-connections/:idp_id' \
  --header 'Authorization: Bearer your_api_key_generated_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "number_users_provisioning_limit": 99
}'
```

### Response samples

- 200

Content type

application/json

Copy
Expand all  Collapse all

`{"__type__": "SsoConnection",

"active": true,

"id": "barker_inc_S6f5ndf8mZqfoBKoxEotMV",

"inserted_at": "2023-06-08T13:47:41",

"number_users_provisioning_limit": 99,

"organization": {"__type__": "Organization",

"allowed_email_domains": ["barker.co"\
\
],

"domain": "barker-inc",

"environments": [{"name": "production",\
\
"status": "down"\
\
},\
\
{"name": "sandbox",\
\
"status": "up"\
\
}\
\
],

"inserted_at": "2023-06-08T12:12:28",

"name": "Barker",

"status": {"errors": [ ],

"estimated_time_to_complete_in_seconds": null,

"progress_in_percentage": null,

"state": "pending"

},

"updated_at": "2023-06-08T12:37:59"

},

"provider_type": "saml.azure_ad",

"saml_config": {"acs_url": "https://www.cryptr.co",

"cryptr_metadata_url": "https://www.cryptr.co",

"entity_id": "shark_academy_MgF6Z9maZKriEBbLM9KZJj",

"slo_response_url": "https://www.cryptr.co",

"slo_url": "https://www.cryptr.co",

"sso_provider_metadata": null

},

"sp_id": "shark_academy_MgF6Z9maZKriEBbLM9KZJj",

"updated_at": "2023-06-08T13:47:41",

"users_access_policy": "provision_new_users"

}`

## [tag/Password](/content/documentation/api/\#tag/Password/index.html) 🔑 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<br>The domain is a **string** value in **lowercase** with **dashes**, generated from the organization’s name. |
| \_\_environment\_\_ | string<br>The environment in which the user is stored, either sandbox (for the test environment) or production. |
| \_\_type\_\_ | string<br>The `__type__` is a **string** that lets you differentiate data types. |
| code | string<br>The code retrieves the **AccessToken** for the user. |
| error | string<br>Description of an error encountered during the challenge process |
| expired\_at | integer<br>The expiration date and time of the Password challenge |
| password\_id | integer<br>The immutable identifier of the actual Password |
| renew\_password | object (PasswordChallenge)  Recursive <br>If the password of the user is expired a renew\_password map will be displayed to help you renew the password. |
| request\_id | uuid<br>The ID of the request |
| user\_id | uuid<br>The immutable identifier of the User |
| valid? | boolean<br>The validity of the Password challenge |

Copy

`{"__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<br>The domain is a **string** value in **lowercase** with **dashes**, generated from the organization’s name. |
| \_\_type\_\_ | string<br>The `__type__` is a **string** that lets you differentiate data types. |
| active | boolean<br>Default: true<br>Specify if the connection is usable. |
| id | string<br>The immutable identifier. |
| inserted\_at | string <date-time> <br>Date time of the insertion |
| pepper\_rotation\_period | integer<br>The time period between each pepper rotation. |
| plain\_text\_max\_length | integer<br>The maximum length of the plain text (password). |
| plain\_text\_min\_length | integer<br>The minimum length of the plain text (password). |
| updated\_at | string <date-time> <br>Update timestamp |

Copy

`{"__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<br>The domain is a **string** value in **lowercase** with **dashes**, generated from the organization’s name. |
| \_\_environment\_\_ | string<br>The environment in which the user is stored, either sandbox (for the test environment) or production. |
| \_\_type\_\_ | string<br>The `__type__` is a **string** that lets you differentiate data types. |
| code | string<br>The code used to retrieve the User AccessToken |
| id | integer<br>The immutable identifier of the new password |
| user\_id | uuid<br>The immutable identifier of the User |

Copy

`{"__domain__": "loirama",

"__environment__": "production",

"__type__": "Password",

"code": "DqwZQU8umrgLBAZXEPRiizjOCpzQJgTXwWya6dX3cXkpESDAgqcgTYKq0TPFeYt6MCv5l1pcg8ySB6FJmNhyA5WhHYyVlQXs2udx",

"id": 145,

"user_id": "9e6e2777-d2bb-42cb-bb7a-13139358d7fa"

}`

## [tag/Password/operation/create-password](/content/documentation/api/\#tag/Password/operation/create-password/index.html) 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<br>required | string<br>Example: org\_domain=loirama<br>The domain is a **string** value in **lowercase** with **dashes**, generated from the organization’s name. |
| user\_email<br>required | string <email> <br>Example: user\_email=it\_person@client.com<br>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<br>Example: password\_code=Zef785dkHgd<br>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.<br>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<br>required | string<br>Example: plain\_text=neripe7845sjHgdeje!<br>The new password of the user as plain text. |

### Responses

**201**

Created

**422**

UnprocessableEntity

post/api/v2/password

https://${{cryptr\_service\_url}}/api/v2/password

### Request samples

- cURL

Copy

```
curl -X POST '${cryptr_service_url}/api/v2/renew-password' \
  -d user_email="lyla@loirama.co" \
  -d password_code="jf78Hgdz5d" \
  -d plain_text="neripe7845sjHgdeje!" \
  -d org_domain="communitiz-app"
```

### Response samples

- 201
- 422

Content type

application/json

Copy

`{"__domain__": "loirama",

"__environment__": "production",

"__type__": "Password",

"code": "DqwZQU8umrgLBAZXEPRiizjOCpzQJgTXwWya6dX3cXkpESDAgqcgTYKq0TPFeYt6MCv5l1pcg8ySB6FJmNhyA5WhHYyVlQXs2udx",

"id": 145,

"user_id": "9e6e2777-d2bb-42cb-bb7a-13139358d7fa"

}`

## [tag/Password/operation/password-challenge](/content/documentation/api/\#tag/Password/operation/password-challenge/index.html) 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<br>Example: org\_domain=loirama<br>The domain is a **string** value in **lowercase** with **dashes**, generated from the organization’s name.<br>**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<br>required | string <email> <br>Example: user\_email=it\_person@client.com<br>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.<br>**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<br>required | string<br>Example: plain\_text=neripe7845sjHgdeje!<br>The password of the user as plain text. |

### Responses

**201**

Created

**404**

Resource Not Found

post/api/v2/password-challenge

https://${{cryptr\_service\_url}}/api/v2/password-challenge

### Request samples

- cURL

Copy

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

### Response samples

- 201
- 404

Content type

application/json

Copy

`{"__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

}`

## [tag/Password/operation/create-password-connection](/content/documentation/api/\#tag/Password/operation/create-password-connection/index.html) 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](/content/documentation/api/#the-password-connection-type/index.html) if the creation succeed.

##### path Parameters

##### query Parameters

|     |     |
| --- | --- |
| plain\_text\_max\_length | integer<br>Example: plain\_text\_max\_length=20<br>The maximum length of the password (should be higher than the minimum length) |
| plain\_text\_min\_length | integer<br>Example: plain\_text\_min\_length=8<br>The minimum length of the password (should be lower than the maximum length) |
| active | boolean<br>Default: true<br>If you want to create but not activate it for now |

### Responses

**201**

Created

**422**

Already exists

post/api/v2/org/{org\_domain}/password-connection

https://${{cryptr\_service\_url}}/api/v2/org/{org\_domain}/password-connection

### Request samples

- cURL

Copy

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

### Response samples

- 201
- 422

Content type

application/json

Copy

`{"__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"

}`

## [tag/Password/operation/password-request](/content/documentation/api/\#tag/Password/operation/password-request/index.html) 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<br>required | string<br>Example: org\_domain=loirama<br>The domain is a **string** value in **lowercase** with **dashes**, generated from the organization’s name. |
| user\_email<br>required | string <email> <br>Example: user\_email=it\_person@client.com<br>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<br>required | string<br>Example: redirect\_uri=https://loirama.com/welcome-back-user<br>URL used to redirect the user after an interaction with a service or application. |
| find\_or\_create\_user | boolean<br>Default: false<br>Example: find\_or\_create\_user=true<br>Flag that finds OR creates the user.<br>- `True`: use the **User**, if and only if it exists, or create the **User**<br>- `False`: **User** MUST exist for challenge creation. |

### Responses

**201**

Requested

**500**

Internal Server Error

post/api/v2/password-request

https://${{cryptr\_service\_url}}/api/v2/password-request

### Request samples

- cURL

Copy

```
curl -X POST '${cryptr_service_url}/api/v2/password-request' \
  -d user_email="lyla@loirama.co" \
  -d org_domain="communitiz-app" \
  -d redirect_uri="https://loirama.com/welcome-back-user"
```

### Response samples

- 201
- 500

Content type

application/json

Copy

`{"__domain__": "loirama",

"__environment__": "production",

"__type__": "PasswordRequest",

"expired_at": "2023-05-04T07:16:56",

"magic_link": "http://loirama.com/password-request/verify/Ouha3JS4pv1OMX5kYsNJiFDD54lPP",

"redirect_uri": "https://loirama.com/welcome-back-user",

"request_id": "4db191b5-6209-4358-9d09-a28b8a8eaab5",

"user_id": "d6a46443-c7bc-4259-aa5d-ce51cc548b57"

}`

## [tag/Password/operation/read-one-password-connection](/content/documentation/api/\#tag/Password/operation/read-one-password-connection/index.html) Retrieve a Password Connection

Retrieve a [Password Connection](/content/documentation/api/#the-password-connection-type/index.html) for an [Organization](/content/documentation/api/#the-organization-type/index.html) 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

### Responses

**200**

OK

get/api/v2/org/{org\_domain}/password-connection

https://${{cryptr\_service\_url}}/api/v2/org/{org\_domain}/password-connection

### Request samples

- cURL

Copy

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

### Response samples

- 200

Content type

application/json

Copy

`{"__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"

}`

## [tag/Password/operation/update-password-connection](/content/documentation/api/\#tag/Password/operation/update-password-connection/index.html) Update a Password Connection

##### path Parameters

##### query Parameters

|     |     |
| --- | --- |
| active | boolean<br>Example: active=false<br>Allows you to activate or disable this password connection for your authentication processes of the selected Organization<br>Set `false` to disable it, set to `true` to enable it |

### Responses

**200**

OK

put/api/v2/org/{org\_domain}/password-connection

https://${{cryptr\_service\_url}}/api/v2/org/{org\_domain}/password-connection

### Request samples

- cURL

Copy

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

### Response samples

- 200

Content type

application/json

Copy

`{"__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"

}`

## [tag/Magic-Link](/content/documentation/api/\#tag/Magic-Link/index.html) ✨ Magic Link

### Magic Link Connection

Cryptr provides a secure solution for **creating**, **managing**, **updating**, and **deleting** connections using magic links. These magic links enable passwordless authentication, simplifying the login process while enhancing security.

Magic Link Connections can be set to **specific organizations'** environments, allowing **user registration** or **restricting access to registered users**. You can **customize** the magic link emails by providing **template IDs** for personalized sign-up experiences.

#### The Magic Link Connection type

|     |     |
| --- | --- |
| \_\_type\_\_ | string<br>Data type |
| active | boolean<br>Default: true<br>Specify if the connection is usable. |
| find\_or\_create\_user | boolean<br>Default: false<br>Flag that finds or creates the user.<br>- `True`: Use the **User** if it exists; otherwise, create the **User**.<br>- `False`: The **User** must exist for challenge creation. |
| id | uuid<br>The unique identifier |
| inserted\_at | string <date-time> <br>Insertion datetime |
| sign\_in\_template\_id | uuid<br>The unique identifier of the email template to use.<br>There are three possible cases:<br>- If the key is not added or its value is not specified, the system will retrieve the first available template.<br>- If the key is added without a value, it temporarily sets the template ID to null.<br>- If the key is added with an existing ID, it will use that specific ID.<br>> 💡 Not required if you do not intend to use the Gateway Process and prefer sending the email yourself. |
| updated\_at | string <date-time> <br>Update datetime |

Copy

`{"__type__": "string",

"active": true,

"find_or_create_user": false,

"id": null,

"inserted_at": "2019-08-24T14:15:22Z",

"sign_in_template_id": null,

"updated_at": "2019-08-24T14:15:22Z"

}`

#### The Magic Link Challenge type

|     |     |
| --- | --- |
| \_\_domain\_\_ | string<br>The domain is a **string** value in **lowercase** with **dashes**, generated from the organization’s name. |
| \_\_environment\_\_ | string<br>The environment in which the user is stored, either sandbox (for the test environment) or production. |
| \_\_type\_\_ | string<br>The `__type__` is a **string** that lets you differentiate data types. |
| code | string<br>The code retrieves the **AccessToken** for the user. |
| email\_address | string<br>The email address of the user. |
| find\_or\_create\_user | boolean<br>Default: false<br>Flag that finds or creates the user.<br>- `True`: Use the **User** if it exists; otherwise, create the **User**.<br>- `False`: The **User** must exist for challenge creation. |
| magic\_link | string<br>The Magic Link sent to the user via email. |
| request\_id | string<br>The ID of the request |

Copy

`{"__domain__": "loirama",

"__environment__": "production",

"__type__": "MagicLinkChallenge",

"code": null,

"email_address": "random@gmail.com",

"find_or_create_user": true,

"magic_link": "https://my_uri.com/eyJhbGciOiJSUzI1NiIsImlzcyI6Imh0dHA6Ly9sb2NhbGhvc3Q6NDAwMC90L2NyeXB0ciIsImtpZCI6IjNmYzE2ODE2LTBmOTktNDg0Zi1iM2QxLTg3YzIyYWUxNWI5YyIsInR5cCI6IkpXVCJ9.eyJhdXRobj8iOmZhbHNlLCJjbGllbnRfaWQiOiJhOTMzYjc1My02NzA1LTQxZTQtYWUyNi1mOWRmNWFhMDVmMmMiLCJlbWFpbCI6InJhbmRvbUBnbWFpbC5jb20iLCJlbnZpcm9ubWVudCI6ImRlZmF1bHQiLCJleHBpcmVkX2F0IjoxNjkxMTg2Mzg5LCJmaW5kX29yX2NyZWF0ZV91c2VyIjp0cnVlLCJvcmdfZG9tYWluIjoiY3J5cHRyIiwicmVkaXJlY3RfdXJpIjoiaHR0cHM6Ly9yZWRpcmVjdF91cmkuY29tIiwicmVxdWVzdF9pZCI6IjRkMTZlZTk4LTdjZTctNDhiMS1hNGE4LTY4ZTJmY2Q3NmU2MyIsInVzZXJfaWQiOm51bGx9.xJ3cJ7KziquzQl5pdLvxDYp-oUGLcCrpETvwhBivh-IGjyk8LMunCeXJhR1gRLdD4PoYZcvRqwDP_oYKNM_xs033pXwVGdicmF3s3W81MJspKt5WDeHEr5Is7FulbRgWRZ0-sZRlvX-MWH4O9Bhdc5WzIOT56jyRqWZZxiOKtYCwsRpnGyUWv-PvmpCLFDBvHCRJ9Hy3hcrHG3vPLqjN4MjyOQsEdKiKVWbJgwG1w73YimOMCWec7mk4o1jMk_ApBtq_BK52kzI6zDdOLNaw-LSdREH60Psn2aCRJnGBCHfsiTqwN0Cnx6GHmxGr7FkmAm2sGmDVF4Ku82DcTQoM4-7gomSL7l83Mk86TA9uxHSy7saRB1a1UZ4ANrayhSZsDxRzT0kLRRx8oswRoRj5t_MsTbtLoB6UP0y7iWCZ7S5abDJ4cVvuOzAoiL_RH3i3CJtFIkKH2kCTVx1nyrbZb3-LSKYiydltAorML9i48v3SyW2XnB2Mone_fed3fkV3swM5lRkjkkYMFnWcvc7zVZFc_sXcutDbXA39svqrzFdpwBhJNEg8U-aJ57OoVoBb9WnNOdYYe9LxvtwHr2nUvjKt9YK67kefjJZDko8UFieMNLg8k72wa27gIwNt5lIIn1NnFZzsD98qvpzzqoHVizmYb8zLmzoUe1lQ5FK_5oo",

"request_id": null

}`

## [tag/Magic-Link/operation/magic-link-challenge](/content/documentation/api/\#tag/Magic-Link/operation/magic-link-challenge/index.html) Create a Magic Link Challenge

Create a Magic Link Challenge to simplify user authentication.

#### RETURNS

Returns information such as the `email_address`, the Magic Link, and other information associated with the Challenge created.

##### query Parameters

### Responses

**201**

Created

**404**

Resource Not Found

post/api/v2/magic-link-challenge

https://${{cryptr\_service\_url}}/api/v2/magic-link-challenge

### Request samples

- cURL

Copy

```
curl -X POST '${cryptr_service_url}/api/v2/magic-link-challenge' \
  -d user_email="lyla@loirama.co" \
  -d redirect_uri="https://loirama.com/welcome-back-user"
```

### Response samples

- 201
- 404

Content type

application/json

Copy

`{"__domain__": "loirama",

"__environment__": "production",

"__type__": "MagicLinkChallenge",

"code": null,

"email_address": "random@gmail.com",

"find_or_create_user": true,

"magic_link": "https://my_uri.com/magic-link/verify/eyJhbGciOiJSUzI1NiIsImlzcyI6Imh0dHA6Ly9sb2NhbGhvc3Q6NDAwMC90L2NyeXB0ciIsImtpZCI6IjNmYzE2ODE2LTBmOTktNDg0Zi1iM2QxLTg3YzIyYWUxNWI5YyIsInR5cCI6IkpXVCJ9.eyJhdXRobj8iOmZhbHNlLCJjbGllbnRfaWQiOiJhOTMzYjc1My02NzA1LTQxZTQtYWUyNi1mOWRmNWFhMDVmMmMiLCJlbWFpbCI6InJhbmRvbUBnbWFpbC5jb20iLCJlbnZpcm9ubWVudCI6ImRlZmF1bHQiLCJleHBpcmVkX2F0IjoxNjkxMTg2Mzg5LCJmaW5kX29yX2NyZWF0ZV91c2VyIjp0cnVlLCJvcmdfZG9tYWluIjoiY3J5cHRyIiwicmVkaXJlY3RfdXJpIjoiaHR0cHM6Ly9yZWRpcmVjdF91cmkuY29tIiwicmVxdWVzdF9pZCI6IjRkMTZlZTk4LTdjZTctNDhiMS1hNGE4LTY4ZTJmY2Q3NmU2MyIsInVzZXJfaWQiOm51bGx9.xJ3cJ7KziquzQl5pdLvxDYp-oUGLcCrpETvwhBivh-IGjyk8LMunCeXJhR1gRLdD4PoYZcvRqwDP_oYKNM_xs033pXwVGdicmF3s3W81MJspKt5WDeHEr5Is7FulbRgWRZ0-sZRlvX-MWH4O9Bhdc5WzIOT56jyRqWZZxiOKtYCwsRpnGyUWv-PvmpCLFDBvHCRJ9Hy3hcrHG3vPLqjN4MjyOQsEdKiKVWbJgwG1w73YimOMCWec7mk4o1jMk_ApBtq_BK52kzI6zDdOLNaw-LSdREH60Psn2aCRJnGBCHfsiTqwN0Cnx6GHmxGr7FkmAm2sGmDVF4Ku82DcTQoM4-7gomSL7l83Mk86TA9uxHSy7saRB1a1UZ4ANrayhSZsDxRzT0kLRRx8oswRoRj5t_MsTbtLoB6UP0y7iWCZ7S5abDJ4cVvuOzAoiL_RH3i3CJtFIkKH2kCTVx1nyrbZb3-LSKYiydltAorML9i48v3SyW2XnB2Mone_fed3fkV3swM5lRkjkkYMFnWcvc7zVZFc_sXcutDbXA39svqrzFdpwBhJNEg8U-aJ57OoVoBb9WnNOdYYe9LxvtwHr2nUvjKt9YK67kefjJZDko8UFieMNLg8k72wa27gIwNt5lIIn1NnFZzsD98qvpzzqoHVizmYb8zLmzoUe1lQ5FK_5oo",

"request_id": null

}`

## [tag/Magic-Link/operation/read-one-magic-link-connection](/content/documentation/api/\#tag/Magic-Link/operation/read-one-magic-link-connection/index.html) Retrieve a Magic Link Connection

Retrieve a [Magic Link Connection](/content/documentation/api/#the-magic-link-connection-type/index.html) for an [Organization](/content/documentation/api/#the-organization-type/index.html) by providing the `org_domain`. This request allows you to obtain information about an existing Magic Link Connection associated with the specified organization.

#### RETURNS

If the request is successful, the API returns an object representing the retrieved Magic Link Connection.

##### path Parameters

### Responses

**200**

OK

get/api/v2/org/{org\_domain}/magic-link-connection

https://${{cryptr\_service\_url}}/api/v2/org/{org\_domain}/magic-link-connection

### Request samples

- cURL

Copy

```
curl '${cryptr_service_url}/api/v2/org/${org_domain}/magic-link-connection'
```

### Response samples

- 200

Content type

application/json

Copy

`{"__type__": "MagicLinkConnection",

"active": true,

"find_or_create_user": false,

"id": "b6f3da01-b571-48c3-a630-6f1fddf5af31",

"inserted_at": "2023-06-08T13:47:41",

"sign_in_template_id": "b653df01-b571-48c3-a630-6f1fddf5af31",

"updated_at": "2023-06-08T13:47:41"

}`

## [tag/Magic-Link/operation/update-magic-link-connection](/content/documentation/api/\#tag/Magic-Link/operation/update-magic-link-connection/index.html) Update a Magic Link Connection

Update a [Magic Link Connection](/content/documentation/api/#the-magic-link-connection-type/index.html) for an [Organization](/content/documentation/api/#the-organization-type/index.html) by providing the `org_domain`, and modify the `find_or_create_user` key to determine whether to automatically register users on their first login or restrict access to existing users.

#### RETURNS

If the request is successful, the API returns an updated **MagicLinkConnection** object, confirming the modifications made to the Magic Link Connection for the specified organization.

##### path Parameters

##### query Parameters

|     |     |
| --- | --- |
| find\_or\_create\_user | boolean<br>Default: false<br>Example: find\_or\_create\_user=true<br>Flag that finds OR creates the user.<br>- `True`: use the **User**, if and only if it exists, or create the **User**<br>- `False`: **User** MUST exist for challenge creation. |
| active | boolean<br>Example: active=true<br>Allows you to activate or disable this **MagicLinkConnection** for authentication processes within the selected organization.<br>Set to `false` to disable it, set to `true` to enable it. |

### Responses

**200**

OK

put/api/v2/org/{org\_domain}/magic-link-connection

https://${{cryptr\_service\_url}}/api/v2/org/{org\_domain}/magic-link-connection

### Request samples

- cURL

Copy

```
curl -X PUT '${cryptr_service_url}/api/v2/org/${org_domain}/magic-link-connection' \
  -d find_or_create_user=${find_or_create_user} \
  -d active=${active} \
```

### Response samples

- 200

Content type

application/json

Copy

`{"__type__": "MagicLinkConnection",

"active": true,

"find_or_create_user": false,

"id": "b6f3da01-b571-48c3-a630-6f1fddf5af31",

"inserted_at": "2023-06-08T13:47:41",

"sign_in_template_id": "b653df01-b571-48c3-a630-6f1fddf5af31",

"updated_at": "2023-06-08T13:47:41"

}`

## [tag/TOTP](/content/documentation/api/\#tag/TOTP/index.html) 🔑 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<br>The `__type__` is a **string** that lets you differentiate data types. |
| challenged\_at | string<br>The date on which the challenge validation took place. |
| code | boolean<br>Default: false<br>The code that the user entered. |
| recovery\_code\_used | boolean<br>Default: false<br>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<br>The unique identifier of the request; creation and validation have different **request\_id** s. |
| sent\_at | string<br>The date when the challenge was created. |
| success | boolean<br>The success status of the challenge. It will be false at creation and should be true at validation. |

Copy

`{"__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<br>The domain is a **string** value in **lowercase** with **dashes**, generated from the organization’s name. |
| active | boolean<br>Determines if the connection is active. |
| expiry\_in\_seconds | integer<br>The expiration time of the TOTP is 30 seconds by default for the TOTP Mobile App and 600 seconds for SMS. |
| method | string<br>The method you want to use (SMS or TOTP Mobile App, default). |

Copy

`{"__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<br>The domain is a **string** value in **lowercase** with **dashes**, generated from the organization’s name. |
| \_\_environment\_\_ | string<br>The environment in which the user is stored, either sandbox (for the test environment) or production. |
| \_\_type\_\_ | string<br>The `__type__` is a **string** that lets you differentiate data types. |
| email | string<br>The email of the user for which an enrollment is requested. |
| enrolled\_totp\_at | string<br>The date on which the enrollment was created. |
| enrollment\_totp\_nb | integer<br>The number of enrollments for a user. |
| first\_verification\_code | string<br>The code that the user should use for SMS enrollment validation.<br>It is only displayed during creation for the SMS method. |
| last\_recovery\_acknowledgement\_at | string<br>The last date on which the user acknowledged receipt of their recovery codes. |
| last\_recovery\_code\_at | string<br>The last date on which the user used a recovery code. |
| recovery\_codes | string<br>The user's recovery codes. These codes are generated only once unless the user is force-enrolled.<br>Each code is separated by '\\n' |
| uri | string<br>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<br>The date on which the enrollment was validated. |

Copy

`{"__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

}`

## [tag/TOTP/operation/create-totp-challenge](/content/documentation/api/\#tag/TOTP/operation/create-totp-challenge/index.html) 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<br>required | string<br>Example: loirama<br>The domain is a **string** value in **lowercase** with **dashes**, generated from the organization’s name.<br>**Please note** that `user_id` and `org_domain` must be provided to Create a TOTP Challenge. |
| user\_id<br>required | uuid<br>Example: 0d34d179-8a81-49e8-b572-289d0e522691<br>User immutable identifier |

### Responses

**201**

Created

**403**

Forbidden

**404**

Resource Not Found

**422**

Unprocessable Entity

post/api/v2/org/{org\_domain}/totp-challenge/{user\_id}

https://${{cryptr\_service\_url}}/api/v2/org/{org\_domain}/totp-challenge/{user\_id}

### Request samples

- cURL

Copy

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

### Response samples

- 201
- 403
- 404
- 422

Content type

application/json

Copy

`{"__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

}`

## [tag/TOTP/operation/create-totp-enrollment](/content/documentation/api/\#tag/TOTP/operation/create-totp-enrollment/index.html) 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<br>required | string<br>Example: loirama<br>The domain is a **string** value in **lowercase** with **dashes**, generated from the organization’s name.<br>**Please note** that both `user_id` and `org_domain` must be provided to create a TOTP enrollment. |
| user\_id<br>required | uuid<br>Example: 0d34d179-8a81-49e8-b572-289d0e522691<br>User immutable identifier |
| force\_enroll | boolean<br>Default: false<br>Example: true<br>If you want to re-enroll a user, even if they have used all their recovery codes, set this value to true.<br>Additionally, generate five new recovery codes upon activation. |

### Responses

**201**

Created

**404**

Resource Not Found

post/api/v2/org/{org\_domain}/totp-enrollment/{user\_id}

https://${{cryptr\_service\_url}}/api/v2/org/{org\_domain}/totp-enrollment/{user\_id}

### Request samples

- cURL

Copy

```
curl -X POST '${cryptr_service_url}/api/v2/org/${org_domain}/totp-enrollment/:user_id' \
-d force_enroll='false'
```

### Response samples

- 201
- 404

Content type

application/json

Copy

`{"__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

}`

## [tag/TOTP/operation/retrieve-totp-connection](/content/documentation/api/\#tag/TOTP/operation/retrieve-totp-connection/index.html) Retrieve a TOTP Connection

Retrieve a [TOTP Connection](/content/documentation/api/#the-totp-connection-type/index.html) for an [Organization](/content/documentation/api/#the-organization-type/index.html) 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](/content/documentation/api/#the-totp-connection-type/index.html) object with an identifier including all the information associated with it.

##### path Parameters

### Responses

**200**

OK

get/api/v2/org/{org\_domain}/totp-connection

https://${{cryptr\_service\_url}}/api/v2/org/{org\_domain}/totp-connection

### Request samples

- cURL

Copy

```
curl -X GET '${cryptr_service_url}/api/v2/org/${org_domain}/totp-connection
```

### Response samples

- 200

Content type

application/json

Copy

`{"__domain__": "loirama",

"active": true,

"expiry_in_seconds": 600,

"method": "sms"

}`

## [tag/TOTP/operation/update-totp-connection](/content/documentation/api/\#tag/TOTP/operation/update-totp-connection/index.html) Update a TOTP Connection

Update a [TOTP Connection](/content/documentation/api/#the-totp-connection-type/index.html) for an [Organization](/content/documentation/api/#the-organization-type/index.html) 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](/content/documentation/api/#the-totp-connection-type/index.html) object with an identifier including all the information entered.

##### path Parameters

##### query Parameters

|     |     |
| --- | --- |
| active | boolean<br>Default: false<br>Example: active=true<br>Boolean that determines whether your TOTP strategy should be enabled or disabled. |
| expiry\_in\_seconds | integer<br>Default: 30<br>Example: expiry\_in\_seconds=600<br>OTP code expiration time in seconds. Default is 600 seconds for SMS method (10 minutes) and 30 seconds for the mobile app method.<br>The maximum validity of a TOTP is 900 seconds (15 minutes), and its minimum duration is 30 seconds.<br>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<br>Default: "totp\_mobile\_app"<br>Example: method=sms<br>Determines the method to be used. Allowed methods are `totp_mobile_app` and `sms`. |

### Responses

**201**

Updated

**422**

Unprocessable Entity

put/api/v2/org/{org\_domain}/totp-connection

https://${{cryptr\_service\_url}}/api/v2/org/{org\_domain}/totp-connection

### Request samples

- cURL

Copy

```
curl -X POST '${cryptr_service_url}/api/v2/org/${org_domain}/totp-connection' \
  -d active='true' \
  -d expiry_in_seconds='30' \
  -d method='totp_mobile_app'
```

### Response samples

- 201
- 422

Content type

application/json

Copy

`{"__domain__": "loirama",

"active": true,

"expiry_in_seconds": 600,

"method": "sms"

}`

## [tag/TOTP/operation/validate-totp-challenge](/content/documentation/api/\#tag/TOTP/operation/validate-totp-challenge/index.html) 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

##### query Parameters

|     |     |
| --- | --- |
| code<br>required | string<br>Example: code=478562<br>The user's TOTP code as plain text. |

### Responses

**201**

Created

**401**

Unauthorized

**403**

Forbidden

**404**

Resource Not Found

**422**

Unprocessable Entity

put/api/v2/org/{org\_domain}/totp-challenge/validation/{user\_id}

https://${{cryptr\_service\_url}}/api/v2/org/{org\_domain}/totp-challenge/validation/{user\_id}

### Request samples

- cURL

Copy

```
curl -X PUT '${cryptr_service_url}/api/v2/org/${org_domain}/totp-challenge/validation/:user_id' \
  -d code='478562'
```

### Response samples

- 201
- 401
- 403
- 404
- 422

Content type

application/json

Copy

`{"__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

}`

## [tag/TOTP/operation/validate-totp-enrollment](/content/documentation/api/\#tag/TOTP/operation/validate-totp-enrollment/index.html) 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<br>required | string<br>Example: loirama<br>The domain is a **string** value in **lowercase** with **dashes**, generated from the organization’s name.<br>**Please note** that both `user_id` and `org_domain` must be provided to create a TOTP enrollment. |
| user\_id<br>required | uuid<br>Example: 0d34d179-8a81-49e8-b572-289d0e522691<br>User immutable identifier |

##### query Parameters

|     |     |
| --- | --- |
| code<br>required | string<br>Example: code=478562<br>The user's TOTP code as plain text. |

### Responses

**200**

OK

**401**

Unauthorized

**404**

Resource Not Found

put/api/v2/org/{org\_domain}/totp-enrollment/validation/{user\_id}

https://${{cryptr\_service\_url}}/api/v2/org/{org\_domain}/totp-enrollment/validation/{user\_id}

### Request samples

- cURL

Copy

```
curl -X PUT '${cryptr_service_url}/api/v2/org/${org_domain}/totp-enrollment/validation/:user_id' \
  -d code='478562'
```

### Response samples

- 200
- 401
- 404

Content type

application/json

Copy

`{"__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"

}`

## [tag/Admin](/content/documentation/api/\#tag/Admin/index.html) ⚙️ 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> <br>**Date** and **time** when the Admin accepted the invitation. |
| color | string<br>The Admin's Logo Color in the Dashboard. |
| declined\_to\_be\_in\_charge\_at | string or null <date-time> <br>**Date** and **time** when the admin declined to be in charge. |
| email | string <email> <br>Administrator's Email |
| id | uuid<br>The immutable identifier |
| inserted\_at | string <date-time> <br>Insertion datetime |
| invited\_at | string <date-time> <br>The **date** and **time** the Admin was invited (creation date). |
| last\_login\_at | string or null <date-time> <br>**Date** and **time** of the Admin's last login. |
| organization | object (Organization) <br>The Organization type |
| updated\_at | string <date-time> <br>Update timestamp |

Copy
Expand all  Collapse all

`{"accepted_invitation_at": null,

"color": "red-500",

"declined_to_be_in_charge_at": null,

"email": "it_sso_person@sso.client.com",

"id": "64a13b92-e635-4931-a96f-5312fe3ba418",

"inserted_at": "2023-06-09T16:22:44",

"invited_at": "2023-06-09T16:22:44",

"last_login_at": null,

"organization": {"__type__": "Organization",

"allowed_email_domains": ["barker.co"\
\
],

"domain": "barker-inc",

"environments": [{"name": "production",\
\
"status": "down"\
\
},\
\
{"name": "sandbox",\
\
"status": "up"\
\
}\
\
],

"inserted_at": "2023-06-08T12:12:28",

"name": "Barker",

"status": {"errors": [ ],

"estimated_time_to_complete_in_seconds": null,

"progress_in_percentage": null,

"state": "pending"

},

"updated_at": "2023-06-08T12:37:59"

},

"updated_at": "2023-06-09T16:22:44"

}`

## [tag/Admin/operation/create-admin](/content/documentation/api/\#tag/Admin/operation/create-admin/index.html) Create the Admin

See the [Admin type](/content/documentation/api/#tag/Admin/index.html) 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](/content/documentation/api/#tag/Admin/index.html) with proper attributes

##### path Parameters

|     |     |
| --- | --- |
| org\_domain<br>required | string<br>Example: shark-academy<br>The domain is a **string** value in **lowercase** with **dashes**, generated from the organization’s name. |

##### query Parameters

|     |     |
| --- | --- |
| email<br>required | string <email> <br>Example: email=it\_sso\_person@sso.client.com<br>The email of the admin of your client that has access to the onboarding. |

### Responses

**201**

Created

**401**

Unauthorized

post/api/v2/org/{org\_domain}/admins

https://${{cryptr\_service\_url}}/api/v2/org/{org\_domain}/admins

### Request samples

- cURL

Copy

```
curl -X POST ${cryptr_service_url}/api/v2/org/${org_domain}/admins
```

### Response samples

- 201
- 401

Content type

application/json

Copy
Expand all  Collapse all

`{"accepted_invitation_at": null,

"color": "red-500",

"declined_to_be_in_charge_at": null,

"email": "it_sso_person@sso.client.com",

"id": "64a13b92-e635-4931-a96f-5312fe3ba418",

"inserted_at": "2023-06-09T16:22:44",

"invited_at": "2023-06-09T16:22:44",

"last_login_at": null,

"organization": {"__type__": "Organization",

"allowed_email_domains": ["barker.co"\
\
],

"domain": "barker-inc",

"environments": [{"name": "production",\
\
"status": "down"\
\
},\
\
{"name": "sandbox",\
\
"status": "up"\
\
}\
\
],

"inserted_at": "2023-06-08T12:12:28",

"name": "Barker",

"status": {"errors": [ ],

"estimated_time_to_complete_in_seconds": null,

"progress_in_percentage": null,

"state": "pending"

},

"updated_at": "2023-06-08T12:37:59"

},

"updated_at": "2023-06-09T16:22:44"

}`

## [tag/Admin/operation/delete-admin](/content/documentation/api/\#tag/Admin/operation/delete-admin/index.html) Delete an Admin

Delete an [Admin](/content/documentation/api/#tag/Admin/index.html) 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](/content/documentation/api/#tag/Admin/index.html) for a valid identifier and email.

##### path Parameters

|     |     |
| --- | --- |
| org\_domain<br>required | string<br>Example: loirama<br>The domain is a **string** value in **lowercase** with **dashes**, generated from the organization’s name. |
| email<br>required | string<br>Example: it\_sso\_person@sso.client.com<br>The email of your Admin |

### Responses

**200**

OK

**401**

Unauthorized

**404**

Not Found

delete/api/v2/org/{org\_domain}/admins/{email}

https://${{cryptr\_service\_url}}/api/v2/org/{org\_domain}/admins/{email}

### Request samples

- cURL

Copy

```
curl -X DELETE '${cryptr_service_url}/api/v2/org/${org_domain}/admins/${email}'
```

### Response samples

- 200
- 401
- 404

Content type

application/json

Copy
Expand all  Collapse all

`{"deleted": true,

"resource": {"accepted_invitation_at": null,

"color": "red-500",

"declined_to_be_in_charge_at": null,

"email": "it_sso_person@sso.client.com",

"id": "64a13b92-e635-4931-a96f-5312fe3ba418",

"inserted_at": "2023-06-09T16:22:44",

"invited_at": "2023-06-09T16:22:44",

"last_login_at": null,

"organization": {"__type__": "Organization",

"allowed_email_domains": ["barker.co"\
\
],

"domain": "barker-inc",

"environments": [{"name": "production",\
\
"status": "down"\
\
},\
\
{"name": "sandbox",\
\
"status": "up"\
\
}\
\
],

"inserted_at": "2023-06-08T12:12:28",

"name": "Barker",

"status": {"errors": [ ],

"estimated_time_to_complete_in_seconds": null,

"progress_in_percentage": null,

"state": "pending"

},

"updated_at": "2023-06-08T12:37:59"

},

"updated_at": "2023-06-09T16:22:44"

}

}`

## [tag/Admin/operation/list-admins](/content/documentation/api/\#tag/Admin/operation/list-admins/index.html) List all Admins

Returns a list of your [Admins](/content/documentation/api/#tag/Admin/index.html). The [Admins](/content/documentation/api/#tag/Admin/index.html) 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](/content/documentation/api/#tag/Admin/index.html). Each entry in the array is a separate [Admin](/content/documentation/api/#tag/Admin/index.html) type. If no [Admins](/content/documentation/api/#tag/Admin/index.html) are available, the resulting array will be empty. This request should never return an error.

##### path Parameters

##### query Parameters

|     |     |
| --- | --- |
| page | integer<br>Example: page=1<br>Precise the page of your listing. |
| per\_page | integer<br>Example: per\_page=2<br>Precise the size of the pages of the pagination of the list. |

### Responses

**200**

OK

**401**

Unauthorized

get/api/v2/org/{org\_domain}/admins

https://${{cryptr\_service\_url}}/api/v2/org/{org\_domain}/admins

### Request samples

- cURL

Copy

```
curl 'https://${cryptr_service_url}/api/v2/org/${org_domain}/admins' \
  -d page=${page}
  -d per_page=${per_page}
```

### Response samples

- 200
- 401

Content type

application/json

Copy
Expand all  Collapse all

`{"__type__": "List",

"data": [{"accepted_invitation_at": null,\
\
"color": "red-500",\
\
"declined_to_be_in_charge_at": null,\
\
"email": "it_sso_person@sso.client.com",\
\
"id": "64a13b92-e635-4931-a96f-5312fe3ba418",\
\
"inserted_at": "2023-06-09T16:22:44",\
\
"invited_at": "2023-06-09T16:22:44",\
\
"last_login_at": null,\
\
"organization": {"__type__": "Organization",\
\
"allowed_email_domains": ["barker.co"\
\
],\
\
"domain": "barker-inc",\
\
"environments": [{"name": "production",\
\
"status": "down"\
\
},\
\
{"name": "sandbox",\
\
"status": "up"\
\
}\
\
],\
\
"inserted_at": "2023-06-08T12:12:28",\
\
"name": "Barker",\
\
"status": {"errors": [ ],\
\
"estimated_time_to_complete_in_seconds": null,\
\
"progress_in_percentage": null,\
\
"state": "pending"\
\
},\
\
"updated_at": "2023-06-08T12:37:59"\
\
},\
\
"updated_at": "2023-06-09T16:22:44"\
\
}\
\
],

"pagination": {"current_page": 1,

"current_pages": [1,\
\
2,\
\
3,\
\
"...",\
\
6\
\
],

"next_page": 2,

"per_page": 2,

"prev_page": null,

"total_pages": 6

},

"total": 11

}`

## [tag/Admin/operation/retrieve-admin](/content/documentation/api/\#tag/Admin/operation/retrieve-admin/index.html) Retrieve an Admin

Fetch an [Admin](/content/documentation/api/#tag/Admin/index.html) 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](/content/documentation/api/#tag/Admin/index.html) for a valid identifier and email.

##### path Parameters

### Responses

**200**

OK

**401**

Unauthorized

**404**

Not Found

get/api/v2/org/{org\_domain}/admins/{email}

https://${{cryptr\_service\_url}}/api/v2/org/{org\_domain}/admins/{email}

### Request samples

- cURL

Copy

```
curl '${cryptr_service_url}/api/v2/org/${org_domain}/admins/${email}'
```

### Response samples

- 200
- 401
- 404

Content type

application/json

Copy
Expand all  Collapse all

`{"accepted_invitation_at": null,

"color": "red-500",

"declined_to_be_in_charge_at": null,

"email": "it_sso_person@sso.client.com",

"id": "64a13b92-e635-4931-a96f-5312fe3ba418",

"inserted_at": "2023-06-09T16:22:44",

"invited_at": "2023-06-09T16:22:44",

"last_login_at": null,

"organization": {"__type__": "Organization",

"allowed_email_domains": ["barker.co"\
\
],

"domain": "barker-inc",

"environments": [{"name": "production",\
\
"status": "down"\
\
},\
\
{"name": "sandbox",\
\
"status": "up"\
\
}\
\
],

"inserted_at": "2023-06-08T12:12:28",

"name": "Barker",

"status": {"errors": [ ],

"estimated_time_to_complete_in_seconds": null,

"progress_in_percentage": null,

"state": "pending"

},

"updated_at": "2023-06-08T12:37:59"

},

"updated_at": "2023-06-09T16:22:44"

}`

## [tag/Webhook-Setup](/content/documentation/api/\#tag/Webhook-Setup/index.html) 🔄 Webhook Setup

The [Webhook](/content/documentation/api/#the-webhook-type/index.html) 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<br>The environment in which the user is stored, either sandbox (for the test environment) or production. |
| \_\_type\_\_ | string<br>The `__type__` is a **string** that lets you differentiate data types. |
| active | boolean<br>Indicates whether the webhook is active. |
| event\_codes | Array of enum<br>Identifiers used to specify types of events within a webhook |
| id | string<br>A unique string that identifies a specific webhook. |
| inserted\_at | string <date-time> <br>Insertion datetime |
| name | string<br>The name of your webhook, which serves as a label to help you understand its purpose. |
| signature\_key | string<br>This value ensures the integrity of the response and authenticates the author. |
| target\_url | string<br>Refers to the specific URL where you want to receive event information. |
| updated\_at | string <date-time> <br>Updated datetime |

Copy
Expand all  Collapse all

`{"__environment__": "sandbox",

"__type__": "Webhook",

"active": true,

"event_codes": ["dir_sync.user.provision.success"\
\
],

"id": "webhook_2RCVpicx8L7cFwhrz2gHjnsCLKQ",

"inserted_at": "2023-06-14T14:50:34",

"name": "My Webhook Name",

"signature_key": "Rjyhf8JcIfPtUhagKRKsu2Delq0JR3z6huEuJJLUwTaK8U380sA1tEgY_4aJYaRNbh_s2-u5_IWbrWQBV_DiDWAX1XNEV6DHDV8cvYGo00PkA32yWrwgEEG9ajbQ-IIT",

"target_url": "http://webhook.site",

"updated_at": "2023-06-14T14:50:34"

}`

## [tag/Webhook-Setup/operation/create-webhook](/content/documentation/api/\#tag/Webhook-Setup/operation/create-webhook/index.html) 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<br>required | string<br>Example: name=My Webhook Name<br>The name of your webhook you can set it to anything you want |
| event\_codes\[\]<br>required | Array of strings<br>Example: event\_codes\[\]=dir\_sync.user.provision.success<br>Identifiers used to specify types of events within a webhook. |
| target\_url<br>required | string<br>Example: target\_url=http://webhook.site<br>Refers to the specific URL where you want to receive event information. |

### Responses

**201**

Created

**422**

Unprocessable Entity

post/api/v2/webhooks

https://${{cryptr\_service\_url}}/api/v2/webhooks

### Request samples

- cURL

Copy

```
curl -X POST '${cryptr_service_url}/api/v2/webhooks' \
  -d 'name=New Webhook' \
  -d 'target_url=https://webhook.site' \
  -d 'event_codes=dir_sync.user.provision.success'
```

### Response samples

- 201
- 422

Content type

application/json

Copy
Expand all  Collapse all

`{"__environment__": "sandbox",

"__type__": "Webhook",

"active": true,

"event_codes": ["dir_sync.user.provision.success"\
\
],

"id": "webhook_2RCVpicx8L7cFwhrz2gHjnsCLKQ",

"inserted_at": "2023-06-14T14:50:34",

"name": "My Webhook Name",

"signature_key": "Rjyhf8JcIfPtUhagKRKsu2Delq0JR3z6huEuJJLUwTaK8U380sA1tEgY_4aJYaRNbh_s2-u5_IWbrWQBV_DiDWAX1XNEV6DHDV8cvYGo00PkA32yWrwgEEG9ajbQ-IIT",

"target_url": "http://webhook.site",

"updated_at": "2023-06-14T14:50:34"

}`

## [tag/Webhook-Setup/operation/delete-webhook](/content/documentation/api/\#tag/Webhook-Setup/operation/delete-webhook/index.html) Delete a Webhook

Use the request below when you want to delete a Webhook.

#### RETURNS

The deleted Webhook

##### path Parameters

|     |     |
| --- | --- |
| id<br>required | string<br>Example: webhook\_2R6eHbyzOezQhb3gkhAlqclt6oT<br>A unique string that identifies a specific webhook. |

### Responses

**200**

OK

**404**

Not Found

delete/api/v2/webhooks/{id}

https://${{cryptr\_service\_url}}/api/v2/webhooks/{id}

### Request samples

- cURL

Copy

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

### Response samples

- 200
- 404

Content type

application/json

Copy
Expand all  Collapse all

`{"deleted": true,

"resource": {"__environment__": "sandbox",

"__type__": "Webhook",

"active": true,

"event_codes": ["dir_sync.user.provision.success"\
\
],

"id": "webhook_2RCVpicx8L7cFwhrz2gHjnsCLKQ",

"inserted_at": "2023-06-14T14:50:34",

"name": "My Webhook Name",

"signature_key": "Rjyhf8JcIfPtUhagKRKsu2Delq0JR3z6huEuJJLUwTaK8U380sA1tEgY_4aJYaRNbh_s2-u5_IWbrWQBV_DiDWAX1XNEV6DHDV8cvYGo00PkA32yWrwgEEG9ajbQ-IIT",

"target_url": "http://webhook.site",

"updated_at": "2023-06-14T14:50:34"

}

}`

## [tag/Webhook-Setup/operation/list-webhooks](/content/documentation/api/\#tag/Webhook-Setup/operation/list-webhooks/index.html) List all Webhooks

Retrieve all your organization’s [Webhooks](/content/documentation/api/#the-webhook-type/index.html) 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](/content/documentation/api/#the-webhook-type/index.html) for a valid organization/environment pair. If no Webhooks exist, an empty list is displayed.

##### query Parameters

### Responses

**200**

OK

get/api/v2/webhooks

https://${{cryptr\_service\_url}}/api/v2/webhooks

### Request samples

- cURL

Copy

```
curl '${cryptr_service_url}/api/v2/webhooks' \
  -d "page=${page}" \
  -d "per_page=${per_page}" \
```

### Response samples

- 200

Content type

application/json

Copy
Expand all  Collapse all

`{"__type__": "List",

"data": [{"__environment__": "sandbox",\
\
"__type__": "Webhook",\
\
"active": true,\
\
"event_codes": ["dir_sync.user.provision.success"\
\
],\
\
"id": "webhook_2REPA0hJihspyjNTrfeLZYrOYS2",\
\
"inserted_at": "2023-06-15T06:55:19",\
\
"name": "My Webhook Name",\
\
"signature_key": "VmL3Gsslj_IWyM4KYmpBYF1URbyHWdOMrogPjD0-yN1nrRPIyPlfr3U-Jv-jonQwRgYkJ6io4a-P_tycQ1ci9ZIfCzACvVNQQYBQzULQ9RPrO7XhMuYGK07XrqHWU2jS",\
\
"target_url": "http://webhook.site",\
\
"updated_at": "2023-06-15T06:55:19"\
\
},\
\
{"__environment__": "sandbox",\
\
"__type__": "Webhook",\
\
"active": true,\
\
"event_codes": ["dir_sync.activate.success",\
\
"dir_sync.deactivate.success"\
\
],\
\
"id": "webhook_2RCVuHlyhadTW8IJfrbjU2KW4G1",\
\
"inserted_at": "2023-06-14T14:51:10",\
\
"name": "Super Webhook",\
\
"signature_key": "4qmmFSOoZQLhlhV50bkNgp0SZt9EpNApUAToYLlFpgRYI-eJ7XHb9KDTuVtEhf7VKSb-0mySqUNRxo54IZ7hj-UxNP6RboQt4sUh0A-Rnt8rD6ERhDRG2Tzhl5V-q1h7",\
\
"target_url": "https://www.cryptr.co",\
\
"updated_at": "2023-06-14T14:51:10"\
\
},\
\
{"__environment__": "sandbox",\
\
"__type__": "Webhook",\
\
"active": true,\
\
"event_codes": ["sso_saml.user.jit_provision.success",\
\
"sso_saml.user.update.success"\
\
],\
\
"id": "webhook_2RCTwiofROfxs3NTkx5BpsmwTUg",\
\
"inserted_at": "2023-06-14T14:35:03",\
\
"name": "Super Webhook",\
\
"signature_key": "sTyVwG3b3A_01bhzQolwtxiDce1DAwm_lz_6BBLBouxvjCZBykJmVa2pDmcOkAjkgJkrXvM9lhVo2bI9cctUqXN7QMWkfcU6LgqZKgUMJ2onA-ccA2CjJw_a2zIXGtqU",\
\
"target_url": "https://www.cryptr.co",\
\
"updated_at": "2023-06-14T14:35:03"\
\
}\
\
],

"pagination": {"current_page": 1,

"current_pages": [1,\
\
2,\
\
3,\
\
"...",\
\
6\
\
],

"next_page": 2,

"per_page": 3,

"prev_page": null,

"total_pages": 6

},

"total": 16

}`

## [tag/Webhook-Setup/operation/retrieve-webhook](/content/documentation/api/\#tag/Webhook-Setup/operation/retrieve-webhook/index.html) Retrieve a Webhook

Retrieve [Webhook](/content/documentation/api/#the-webhook-type/index.html) 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](/content/documentation/api/#the-webhook-type/index.html) for a valid organization/environment pair. If it’s for a deleted [Webhook](/content/documentation/api/#the-webhook-type/index.html), a **Not Found** response is displayed.

##### path Parameters

|     |     |
| --- | --- |
| id<br>required | string<br>Example: webhook\_2R6eHbyzOezQhb3gkhAlqclt6oT<br>A unique string that identifies a specific webhook. |

### Responses

**200**

OK

**404**

Not Found

get/api/v2/webhooks/{id}

https://${{cryptr\_service\_url}}/api/v2/webhooks/{id}

### Request samples

- cURL

Copy

```
curl '${cryptr_service_url}/api/v2/webhooks/${id}'
```

### Response samples

- 200
- 404

Content type

application/json

Copy
Expand all  Collapse all

`{"__environment__": "sandbox",

"__type__": "Webhook",

"active": true,

"event_codes": ["dir_sync.user.provision.success"\
\
],

"id": "webhook_2RCVpicx8L7cFwhrz2gHjnsCLKQ",

"inserted_at": "2023-06-14T14:50:34",

"name": "My Webhook Name",

"signature_key": "Rjyhf8JcIfPtUhagKRKsu2Delq0JR3z6huEuJJLUwTaK8U380sA1tEgY_4aJYaRNbh_s2-u5_IWbrWQBV_DiDWAX1XNEV6DHDV8cvYGo00PkA32yWrwgEEG9ajbQ-IIT",

"target_url": "http://webhook.site",

"updated_at": "2023-06-14T14:50:34"

}`

## [tag/Webhook-Setup/operation/update-webhook](/content/documentation/api/\#tag/Webhook-Setup/operation/update-webhook/index.html) Update a Webhook

Update an existing [Webhook](/content/documentation/api/#the-webhook-type/index.html) 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](/content/documentation/api/#the-webhook-type/index.html) for a valid organization/environment pair. If not found, a **404 Not Found** response is displayed.

##### path Parameters

|     |     |
| --- | --- |
| id<br>required | string<br>Example: webhook\_2R6eHbyzOezQhb3gkhAlqclt6oT<br>A unique string that identifies a specific webhook. |

##### query Parameters

|     |     |
| --- | --- |
| event\_codes\[\] | Array of strings<br>Example: event\_codes\[\]=sso\_saml.user.jit\_provision.success<br>Identifiers used to specify types of events within a webhook. See the [full list of events](/content/documentation/index.html) |
| target\_url | string<br>Example: target\_url=http://webhook.site<br>Refers to the specific URL where you want to receive event information. |
| name | string<br>Example: name=My Webhook Name<br>The name of your webhook you can set it to anything you want. |

### Responses

**200**

OK

**404**

Not Found

put/api/v2/webhooks/{id}

https://${{cryptr\_service\_url}}/api/v2/webhooks/{id}

### Request samples

- cURL

Copy

```
curl -X PUT '${cryptr_service_url}/api/v2/webhooks/${id}' \
  -d "event_codes[]=sso_saml.user.jit_provision.success" \
  -d "target_url=http://webhook.site" \
  -d "name=My Webhook Name"
```

### Response samples

- 200
- 404

Content type

application/json

Copy
Expand all  Collapse all

`{"__environment__": "sandbox",

"__type__": "Webhook",

"active": true,

"event_codes": ["dir_sync.user.provision.success"\
\
],

"id": "webhook_2RCVpicx8L7cFwhrz2gHjnsCLKQ",

"inserted_at": "2023-06-14T14:50:34",

"name": "My Webhook Name",

"signature_key": "Rjyhf8JcIfPtUhagKRKsu2Delq0JR3z6huEuJJLUwTaK8U380sA1tEgY_4aJYaRNbh_s2-u5_IWbrWQBV_DiDWAX1XNEV6DHDV8cvYGo00PkA32yWrwgEEG9ajbQ-IIT",

"target_url": "http://webhook.site",

"updated_at": "2023-06-14T14:50:34"

}`

## [tag/Webhook-Events](/content/documentation/api/\#tag/Webhook-Events/index.html) 📊 Webhook Events

### The Webhook Event type

|     |     |
| --- | --- |
| \_\_type\_\_ | string<br>The `__type__` is a **string** that lets you differentiate data types. |
| args | object (Event) <br>The payload of the Webhook Event that was sent to you. |
| attempt | integer<br>The number of attempts that have been made. |
| attempted\_at | string<br>The last date on which an attempt was made. |
| cancelled\_at | string<br>The date on which the event sending was cancelled. |
| completed\_at | string<br>The date on which the event sending was successful. |
| discarded\_at | string<br>The date when the event sending was discarded. |
| id | integer<br>Immutable identifier. |
| inserted\_at | string <date-time> <br>Insertion datetime |
| max\_attempts | integer<br>The maximum number of attempts to send the event. Maximum is 5 unless you use the retry-after option. |
| scheduled\_at | string<br>The date on which the event sending was scheduled. |
| state | string<br>The states of the event sending. The different states are:<br>- `available`: Webhook events in the **available** state can be sent to your endpoint.<br>  <br>- `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**.<br>  <br>- `executing`: Webhook events in the **executing** state are currently being sent to your endpoint.<br>  <br>- `retryable`: Webhook events in the **retryable** state can be resent to your endpoint after a failure.<br>  <br>- `completed`: Webhook events in the **completed** state have already been sent and successfully received.<br>  <br>- `cancelled`: Webhook events in the **cancelled** state have been cancelled.<br>  <br>- `discarded`: Webhook events in the **discarded** state have reached their sending limits or can no longer be sent. |

Copy
Expand all  Collapse all

`{"__type__": "WebhookEvent",

"args": {"__domain__": "shark-academy",

"__environment__": "sandbox",

"__type__": "Event",

"code": "dir_sync.activate.success",

"data": {"__type__": "DirectorySyncEvent",

"directory_sync_id": "f71c2961-ebbd-4364-a6bd-e585614b9458",

"provider": "okta"

},

"issued_at": "2023-06-13T08:57:59.617402Z",

"webhook_id": "webhook_2QbwnDHL6z4TsohFvzOoE74NBvJ"

},

"attempt": 1,

"attempted_at": "2023-06-13T08:57:59.632125Z",

"cancelled_at": null,

"completed_at": "2023-06-13T08:57:59.761073Z",

"discarded_at": null,

"id": 80,

"inserted_at": "2023-06-13T08:57:59.621406Z",

"max_attempts": 5,

"scheduled_at": "2023-06-13T08:57:59.621406Z",

"state": "completed"

}`

## [tag/Webhook-Events/operation/cancel-webhook-events](/content/documentation/api/\#tag/Webhook-Events/operation/cancel-webhook-events/index.html) 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](/content/api#tag/Webhook-Events/index.html) you requested to cancel don’t exist or if an error occurred, an error message will be sent.

##### path Parameters

|     |     |
| --- | --- |
| id<br>required | int<br>Example: 42<br>Unique identifier assigned to a webhook event. |

### Responses

**200**

OK

**404**

Not Found

post/api/v2/webhook-events/{id}/cancel

https://${{cryptr\_service\_url}}/api/v2/webhook-events/{id}/cancel

### Request samples

- cURL

Copy

```
curl -X POST '${cryptr_service_url}/api/v2/webhook-events/${id}/cancel'
```

### Response samples

- 200
- 404

Content type

application/json

Copy
Expand all  Collapse all

`{"__type__": "WebhookEvent",

"args": {"__domain__": "shark-academy",

"__environment__": "sandbox",

"__type__": "Event",

"code": "dir_sync.activate.success",

"data": {"__domain__": "shark-academy",

"__type__": "DirectorySyncEvent",

"change": "create",

"directory_sync_id": "14630346-0cd3-4cc6-8f88-9ca27e3f60fe",

"provider": "okta",

"resource": {"changes": {"new_values": {"__domain__": "shark-academy",

"__environment__": "sandbox",

"__type__": "User",

"address": {"country": "BE",

"formatted": "3 Heathcote Mall\n44843 New Fabiola, Belgium",

"locality": "New Fabiola",

"postal_code": "44843",

"region": "Florida",

"street_address": "3 Heathcote Mall"

},

"email": "madilyn.blanda@gutmann.com",

"email_verified": false,

"id": "bcee32ef-475a-4ada-8b58-a0cc516a3b7d",

"inserted_at": "2023-06-13T13:14:22",

"meta_data": [ ],

"phone_number": null,

"phone_number_verified": false,

"profile": {"birthdate": "1970-08-18",

"family_name": "Blanchet",

"gender": null,

"given_name": "Estelle",

"locale": "en_US",

"nickname": "Ginette",

"picture": "https://robohash.org/set_set1/bgset_bg2/yUwVdc0f",

"preferred_username": "kiley.gleason",

"website": "https://mayer.biz",

"zoneinfo": "America/Chicago"

},

"updated_at": "2023-06-13T13:14:22"

},

"previous_values": null

},

"id": "user_c8fcaf9d-fcbf-4b6f-a37f-70ec75d1a144",

"type": "User"

}

},

"issued_at": "2023-06-13T09:03:18.750478Z",

"webhook_id": "webhook_2QbwnDHL6z4TsohFvzOoE74NBvJ"

},

"attempt": 1,

"attempted_at": "2023-06-13T09:03:18.819155Z",

"cancelled_at": "2023-06-15T15:17:33.666466Z",

"completed_at": "2023-06-13T09:03:18.920373Z",

"discarded_at": null,

"id": 81,

"inserted_at": "2023-06-13T09:03:18.754610Z",

"max_attempts": 5,

"scheduled_at": "2023-06-13T09:03:18.754610Z",

"state": "cancelled"

}`

## [tag/Webhook-Events/operation/list-webhook-events](/content/documentation/api/\#tag/Webhook-Events/operation/list-webhook-events/index.html) 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](/content/api#tag/Webhook-Events/index.html).

##### query Parameters

### Responses

**200**

OK

get/api/v2/webhook-events

https://${{cryptr\_service\_url}}/api/v2/webhook-events

### Request samples

- cURL

Copy

```
curl '${cryptr_service_url}/api/v2/webhook-events'
  -d "page=${page}" \
  -d "per_page=${per_page}" \
```

### Response samples

- 200

Content type

application/json

Copy
Expand all  Collapse all

`{"__type__": "List",

"data": [{"__type__": "WebhookEvent",\
\
"args": {"__domain__": "follow-the-market",\
\
"__environment__": "production",\
\
"__type__": "Event",\
\
"code": "dir_sync.user.create.success",\
\
"data": {"__domain__": "shark-academy",\
\
"__type__": "DirectorySyncEvent",\
\
"change": "create",\
\
"directory_sync_id": "14630346-0cd3-4cc6-8f88-9ca27e3f60fe",\
\
"provider": "okta",\
\
"resource": {"changes": {"new_values": {"__domain__": "shark-academy",\
\
"__environment__": "sandbox",\
\
"__type__": "User",\
\
"address": {"country": "BE",\
\
"formatted": "3 Heathcote Mall\n44843 New Fabiola, Belgium",\
\
"locality": "New Fabiola",\
\
"postal_code": "44843",\
\
"region": "Florida",\
\
"street_address": "3 Heathcote Mall"\
\
},\
\
"email": "madilyn.blanda@gutmann.com",\
\
"email_verified": false,\
\
"id": "bcee32ef-475a-4ada-8b58-a0cc516a3b7d",\
\
"inserted_at": "2023-06-13T13:14:22",\
\
"meta_data": [ ],\
\
"phone_number": null,\
\
"phone_number_verified": false,\
\
"profile": {"birthdate": "1970-08-18",\
\
"family_name": "Blanchet",\
\
"gender": null,\
\
"given_name": "Estelle",\
\
"locale": "en_US",\
\
"nickname": "Ginette",\
\
"picture": "https://robohash.org/set_set1/bgset_bg2/yUwVdc0f",\
\
"preferred_username": "kiley.gleason",\
\
"website": "https://mayer.biz",\
\
"zoneinfo": "America/Chicago"\
\
},\
\
"updated_at": "2023-06-13T13:14:22"\
\
},\
\
"previous_values": null\
\
},\
\
"id": "user_c8fcaf9d-fcbf-4b6f-a37f-70ec75d1a144",\
\
"type": "User"\
\
}\
\
},\
\
"issued_at": "~U[2023-05-17 10:38:13.339032Z]",\
\
"webhook_id": "webhook_id"\
\
},\
\
"attempt": 1,\
\
"attempted_at": "~U[2023-05-17 10:38:13.447032Z]",\
\
"attempted_by": null,\
\
"cancelled_at": null,\
\
"completed_at": "~U[2023-05-17 10:38:13.449032Z]",\
\
"discarded_at": null,\
\
"inserted_at": "~U[2023-05-17 10:38:13.439032Z]",\
\
"max_attempts": 5,\
\
"scheduled_at": "~U[2023-05-17 10:38:17.000000Z]",\
\
"state": "scheduled"\
\
}\
\
],

"pagination": {"current_page": 1,

"current_pages": [1\
\
],

"next_page": null,

"per_page": 10,

"prev_page": null,

"total_pages": 1

},

"total": 1

}`

## [tag/Webhook-Events/operation/retry-webhook-events](/content/documentation/api/\#tag/Webhook-Events/operation/retry-webhook-events/index.html) 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](/content/api#tag/Webhook-Events/index.html) you requested for retry do not exist or if an error occurs, an error message will be sent.

##### path Parameters

|     |     |
| --- | --- |
| id<br>required | int<br>Example: 42<br>Unique identifier assigned to a webhook event. |

### Responses

**200**

OK

**404**

Not Found

post/api/v2/webhook-events/{id}/retry

https://${{cryptr\_service\_url}}/api/v2/webhook-events/{id}/retry

### Request samples

- cURL

Copy

```
curl -X POST '${cryptr_service_url}/api/v2/webhook-events/${id}/retry'
```

### Response samples

- 200
- 404

Content type

application/json

Copy
Expand all  Collapse all

`{"__type__": "WebhookEvent",

"args": {"__domain__": "shark-academy",

"__environment__": "sandbox",

"__type__": "Event",

"code": "dir_sync.activate.success",

"data": {"__domain__": "shark-academy",

"__type__": "DirectorySyncEvent",

"change": "create",

"directory_sync_id": "14630346-0cd3-4cc6-8f88-9ca27e3f60fe",

"provider": "okta",

"resource": {"changes": {"new_values": {"__domain__": "shark-academy",

"__environment__": "sandbox",

"__type__": "User",

"address": {"country": "BE",

"formatted": "3 Heathcote Mall\n44843 New Fabiola, Belgium",

"locality": "New Fabiola",

"postal_code": "44843",

"region": "Florida",

"street_address": "3 Heathcote Mall"

},

"email": "madilyn.blanda@gutmann.com",

"email_verified": false,

"id": "bcee32ef-475a-4ada-8b58-a0cc516a3b7d",

"inserted_at": "2023-06-13T13:14:22",

"meta_data": [ ],

"phone_number": null,

"phone_number_verified": false,

"profile": {"birthdate": "1970-08-18",

"family_name": "Blanchet",

"gender": null,

"given_name": "Estelle",

"locale": "en_US",

"nickname": "Ginette",

"picture": "https://robohash.org/set_set1/bgset_bg2/yUwVdc0f",

"preferred_username": "kiley.gleason",

"website": "https://mayer.biz",

"zoneinfo": "America/Chicago"

},

"updated_at": "2023-06-13T13:14:22"

},

"previous_values": null

},

"id": "user_c8fcaf9d-fcbf-4b6f-a37f-70ec75d1a144",

"type": "User"

}

},

"issued_at": "2023-06-13T09:03:18.750478Z",

"webhook_id": "webhook_2QbwnDHL6z4TsohFvzOoE74NBvJ"

},

"attempt": 1,

"attempted_at": "2023-06-13T09:03:18.819155Z",

"cancelled_at": null,

"completed_at": "2023-06-13T09:03:18.920373Z",

"discarded_at": null,

"id": 81,

"inserted_at": "2023-06-13T09:03:18.754610Z",

"max_attempts": 5,

"scheduled_at": "2023-06-13T09:03:18.754610Z",

"state": "available"

}`

## [tag/Webhook-Events/operation/test-webhook-events](/content/documentation/api/\#tag/Webhook-Events/operation/test-webhook-events/index.html) 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<br>required | string<br>Example: event\_code=dir\_sync.user.update.success<br>The event code for which you want to simulate a fake event. |

### Responses

**200**

OK

post/api/v2/webhook-events/trigger-test

https://${{cryptr\_service\_url}}/api/v2/webhook-events/trigger-test

### Request samples

- cURL

Copy

```
curl -X POST '${cryptr_service_url}/api/v2/webhook-events/trigger-test'             --header 'Authorization: Bearer your_api_key_generated_token' \
    --header 'Content-Type: application/json' \
    -d event_code="dir_sync.user.update.success"
```

### Response samples

- 200

Content type

application/json

Copy
Expand all  Collapse all

`{"__type__": "WebhookEventTest",

"preview": {"__domain__": "shark-academy",

"__environment__": "sandbox",

"__type__": "Event",

"code": "dir_sync.user.provision.success",

"data": {"__domain__": "shark-academy",

"__type__": "DirectorySyncEvent",

"change": "create",

"directory_sync_id": "70b4ee66-4d2d-45ed-b351-292727ba0050",

"provider": "okta",

"resource": {"changes": {"new_values": {"__domain__": "shark-academy",

"__environment__": "sandbox",

"__type__": "User",

"address": {"country": "FR",

"formatted": "0465 Lelah Fields\n78361 Kshlerin, France",

"locality": "Kshlerin",

"postal_code": "78361",

"region": "New Hampshire",

"street_address": "0465 Lelah Fields"

},

"email": "reymundo2060@spencer.biz",

"email_verified": false,

"id": "7862c0ce-2c3d-4045-95f1-d1fb942b71a0",

"inserted_at": "2023-06-13T13:14:22",

"meta_data": [ ],

"phone_number": null,

"phone_number_verified": false,

"profile": {"birthdate": "1929-07-20",

"family_name": "Vernier",

"gender": null,

"given_name": "Pierre",

"locale": "fr_FR",

"nickname": "Victor",

"picture": "https://robohash.org/set_set3/bgset_bg1/n86s5A6H9Bn",

"preferred_username": "sienna2028",

"website": "http://kessler.net",

"zoneinfo": "America/Chicago"

},

"updated_at": "2023-06-13T13:14:22"

},

"previous_values": null

},

"id": "user_2771734b-4d4a-46c5-bd08-56ef6a3089a0",

"type": "User"

}

},

"issued_at": "2023-06-27T09:37:03.745212Z",

"webhook_id": "webhook_2RmcDyFCS3jOwaGNh0NufCrpbBD"

},

"triggered_webhooks": [{"__environment__": "sandbox",\
\
"__type__": "Webhook",\
\
"active": true,\
\
"event_codes": ["dir_sync.user.provision.success"\
\
],\
\
"id": "webhook_2RmcDyFCS3jOwaGNh0NufCrpbBD",\
\
"inserted_at": "2023-06-27T09:36:20",\
\
"name": "My Webhook Name",\
\
"signature_key": "6H0dAygazkUpiJJe_oMajpNVuFz6QvkSVHYvYzLCArqiOFWXTwaVJFFBOk1xBOg0vX81TKTtW4Md48KJ_ah3SQRUt0W8J1a_ayXTA4tX-srnMDPRzzkNablSms7pVqp4",\
\
"target_url": "http://webhook.site",\
\
"updated_at": "2023-06-27T09:36:20"\
\
}\
\
],

"untriggered_webhooks": [ ]

}`

## [tag/RedirectUris](/content/documentation/api/\#tag/RedirectUris/index.html) 🔂 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<br>The environment in which the user is stored, either sandbox (for the test environment) or production. |
| \_\_type\_\_ | string<br>Data type |
| default | boolean<br>Default: false<br>If it’s the default for its environment, it cannot be deleted if `true`. |
| id | uuid<br>The immutable identifier |
| inserted\_at | string <date-time> <br>Insertion datetime |
| updated\_at | string <date-time> <br>Update timestamp |
| url | url<br>URL to which the user will be redirected after a successful authentication |

Copy

`{"__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"

}`

## [tag/RedirectUris/operation/create-redirect-uri](/content/documentation/api/\#tag/RedirectUris/operation/create-redirect-uri/index.html) Create a Redirect URI

Create [Redirect URI](/content/documentation/api/#the-redirect-uri-type/index.html) for an environment by specifying the `url`
to allow redirection after successful authentication.

#### RETURNS

Returns [Redirect URI](/content/documentation/api/#the-redirect-uri-type/index.html) attached to the environment if creation succeeded.
Returns an error if creation failed

##### query Parameters

|     |     |
| --- | --- |
| url<br>required | url<br>Example: url=https://my-saas.app<br>The strict URL to redirect to after successful authentication of the end-user. |

### Responses

**201**

Created

**422**

Unprocessable Entity

post/api/v2/redirect\_uris

https://${{cryptr\_service\_url}}/api/v2/redirect\_uris

### Request samples

- cURL

Copy

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

### Response samples

- 201
- 422

Content type

application/json

Copy

`{"__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"

}`

## [tag/RedirectUris/operation/delete-redirect-uri](/content/documentation/api/\#tag/RedirectUris/operation/delete-redirect-uri/index.html) Delete a Redirect URI

Delete a [Redirect URI](/content/documentation/api/#the-redirect-uri-type/index.html) for an environment.

#### RETURNS

Returns the deleted [Redirect URI](/content/documentation/api/#the-redirect-uri-type/index.html) for an environment/

##### path Parameters

|     |     |
| --- | --- |
| id<br>required | uuid<br>Example: 20c8da6b-8086-45f8-b767-990e5d2f8561<br>The immutable identifier of the Redirect URI you want to retrieve |

### Responses

**200**

OK

**404**

Not Found

**422**

Unprocessable Entity

delete/api/v2/redirect\_uris/{id}

https://${{cryptr\_service\_url}}/api/v2/redirect\_uris/{id}

### Request samples

- cURL

Copy

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

### Response samples

- 200
- 404
- 422

Content type

application/json

Copy
Expand all  Collapse all

`{"deleted": true,

"resource": {"__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"

}

}`

## [tag/RedirectUris/operation/list-redirect-uris](/content/documentation/api/\#tag/RedirectUris/operation/list-redirect-uris/index.html) List all Redirect URIs

Return a list of all [Redirect URI](/content/documentation/api/#the-redirect-uri-type/index.html) 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](/content/documentation/api/#the-redirect-uri-type/index.html).
Each entry in the array represents a separate [Redirect URI](/content/documentation/api/#the-redirect-uri-type/index.html) type.
If no matching [Redirect URI](/content/documentation/api/#the-redirect-uri-type/index.html) is available, the resulting array will be empty. This request should never return an error.

##### query Parameters

### Responses

**200**

OK

get/api/v2/redirect\_uris

https://${{cryptr\_service\_url}}/api/v2/redirect\_uris

### Request samples

- cURL

Copy

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

### Response samples

- 200

Content type

application/json

Copy
Expand all  Collapse all

`{"data": [{"__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"\
\
}\
\
],

"pagination": {"current_page": 4,

"current_pages": [1,\
\
2,\
\
3,\
\
4,\
\
5,\
\
6,\
\
"...",\
\
16\
\
],

"next_page": 5,

"per_page": 2,

"prev_page": 3,

"total_pages": 16

},

"total": 0

}`

## [tag/RedirectUris/operation/retrieve-redirect-uri](/content/documentation/api/\#tag/RedirectUris/operation/retrieve-redirect-uri/index.html) Retrieve a Redirect URI

Retrieve a [Redirect URI](/content/documentation/api/#the-redirect-uri-type/index.html) by specifying its given `id`.

#### RETURNS

Returns a [Redirect URI](/content/documentation/api/#the-redirect-uri-type/index.html) for a valid identifier.
If no match is found, a **Not Found** error will be returned.

##### path Parameters

### Responses

**200**

OK

**404**

Not Found

get/api/v2/redirect\_uris/{id}

https://${{cryptr\_service\_url}}/api/v2/redirect\_uris/{id}

### Request samples

- cURL

Copy

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

### Response samples

- 200
- 404

Content type

application/json

Copy

`{"__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"

}`

## [tag/RedirectUris/operation/set-redirect-uri-as-default](/content/documentation/api/\#tag/RedirectUris/operation/set-redirect-uri-as-default/index.html) Set Redirect URI as default

Set a [Redirect URI](/content/documentation/api/#the-redirect-uri-type/index.html) for its environment.

When a [Redirect URI](/content/documentation/api/#the-redirect-uri-type/index.html) 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](/content/documentation/api/#the-redirect-uri-type/index.html) will be used according to the request’s environment.

#### RETURNS

Returns the [Redirect URI](/content/documentation/api/#the-redirect-uri-type/index.html) with `default` set to **true** if the request succeeds.

##### path Parameters

### Responses

**200**

OK

**404**

Not Found

put/api/v2/redirect\_uris/{id}/set-as-default

https://${{cryptr\_service\_url}}/api/v2/redirect\_uris/{id}/set-as-default

### Request samples

- cURL

Copy

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

### Response samples

- 200
- 404

Content type

application/json

Copy

`{"__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"

}`

## [tag/Token](/content/documentation/api/\#tag/Token/index.html) 🔐 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<br>Token used to allow access to an application. |
| expires\_in | string<br>The token’s validity period. |
| id\_token | boolean<br>Default: false<br>Token used to store user profile information. |
| scope | boolean<br>Default: false<br>The scope of the token. This can be the resource to which a user has access. |
| token\_type | string<br>The type of the **Token**, for example, `Bearer` |

Copy
Expand all  Collapse all

`{"access_token": "eyJhbGciOiJSUzI1NiIsImlzcyI6Imh0...",

"expires_in": 36000,

"id_token": "eyJhbGciOiJSUzI1NiIsImlzcyI6Imh0...",

"scope": ["openid",\
\
"email",\
\
"profile"\
\
],

"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<br>The desired name for this new MetaKey, use something understandable for your use case. |
| required | string<br>A boolean that indicates if the key is required. |
| type | string<br>The type of the data that will be used as value. |

Copy

`{"name": "uid",

"required": false,

"type": "string"

}`

## [tag/Token/operation/create-token](/content/documentation/api/\#tag/Token/operation/create-token/index.html) Create a Token

Create a Token.

#### RETURNS

Returns the Access Token, ID Token...

##### query Parameters

|     |     |
| --- | --- |
| audience | string<br>Example: audience=loirama<br>The audience is, in most cases, the **Account Domain**. |
| client\_id | uuid<br>Example: client\_id=2fd63d8d-8f1d-42f2-9b13-9e698b821e4f<br>The Client ID is your API Key ID. |
| client\_secret | string<br>Example: client\_secret=my-secret<br>The Client Secret is your API Key secret. |
| code | string<br>Example: code=9ukVAuUcYrxPe4VYW5yFLjnP6NBV6a82MMm8FwyV6UUH4hQg4a<br>The code that allows you to generate a token. This code is often obtained after a successful challenge. |
| grant\_type<br>required | enum<br>Enum:"authorization\_code""relay""client\_credentials"<br>Example: grant\_type=authorization\_code<br>The Grant Type of your request |

### Responses

**201**

Created

post/oauth/token

https://${{cryptr\_service\_url}}/oauth/token

### Request samples

- cURL Client Credentials
- cURL Authorization Code
- cURL Relay

Copy

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

- 201

Content type

application/json

Copy
Expand all  Collapse all

`{"access_token": "eyJhbGciOiJSUzI1NiIsImlzcyI6Imh0...",

"expires_in": 36000,

"id_token": "eyJhbGciOiJSUzI1NiIsImlzcyI6Imh0...",

"scope": ["openid",\
\
"email",\
\
"profile"\
\
],

"token_type": "Bearer"

}`

## [tag/Token/operation/create-user-metakey](/content/documentation/api/\#tag/Token/operation/create-user-metakey/index.html) 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](/content/documentation/api#tag/Token/index.html) you just created. You can now specify the value of this key on any `User`, from any `Organization`.

##### query Parameters

|     |     |
| --- | --- |
| name<br>required | string<br>Example: name=uid<br>The desired name for this new MetaKey, use something understandable for your use case |

### Responses

**200**

Created MetaKey response

**401**

Unauthorized

post/api/v2/tokens/user-metakeys

https://${{cryptr\_service\_url}}/api/v2/tokens/user-metakeys

### Request samples

- cURL

Copy

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

### Response samples

- 200
- 401

Content type

application/json

Copy

`{"name": "uid",

"required": false,

"type": "string"

}`

## [tag/Token/operation/list-user-metakey](/content/documentation/api/\#tag/Token/operation/list-user-metakey/index.html) List all User Metakeys

List all stored user `MetaKey`.

#### RETURNS

The list of all user `MetaKey` available on your service

### Responses

**200**

Fetched MetaKey(s) response

**401**

Unauthorized

get/api/v2/tokens/user-metakeys

https://${{cryptr\_service\_url}}/api/v2/tokens/user-metakeys

### Request samples

- cURL

Copy

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

### Response samples

- 200
- 401

Content type

application/json

Copy
Expand all  Collapse all

`[{"name": "uid",\
\
"required": false,\
\
"type": "string"\
\
}\
\
]`

## [tag/Token/operation/remove-user-metakey](/content/documentation/api/\#tag/Token/operation/remove-user-metakey/index.html) 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<br>required | string<br>Example: name=uid<br>The name of the MetaKey |

### Responses

**200**

Deleted MetaKey response

**401**

Unauthorized

**404**

Not Found

delete/api/v2/tokens/user-metakeys

https://${{cryptr\_service\_url}}/api/v2/tokens/user-metakeys

### Request samples

- cURL

Copy

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

### Response samples

- 200
- 401
- 404

Content type

application/json

Copy
Expand all  Collapse all

`{"deleted": true,

"resource": {"name": "uid",

"required": false,

"type": "string"

}

}`