API Reference

Configure an Authentication Provider

POST/v1/users/authentication-providers

Configures an Authentication Provider on the tenant.

An authentication or identity provider (IdP) is a platform that is typically used to store and manage user accounts on behalf of an organization or a service provider. MATTR VII uses the authentication provider to authenticate end users before issuing them credentials.

The /.well-known/openid-configuration endpoint of the Authentication Provider must contain values for the authorization_endpoint, token_endpoint and scopes_supported.

Roles

adminissuermanaged-issuer

Analytics Events

USER_AUTHENTICATION_PROVIDER_CREATE_STARTUSER_AUTHENTICATION_PROVIDER_CREATE_SUCCESSUSER_AUTHENTICATION_PROVIDER_CREATE_FAIL

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Request Body

application/json

The Authentication Provider payload

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

`application/json`

curl -X POST "https://example.com/v1/users/authentication-providers" \  -H "Content-Type: application/json" \  -d '{    "clientId": "vJ0SCKchr4XjC0xHNE8DkH6Pmlg2lkCN"  }'

{  "id": "983c0a86-204f-4431-9371-f5a22e506599",  "redirectUrl": "https://tenant.vii.mattr.global/v1/oauth/authentication/callback",  "url": "http://example.com",  "scope": [    "openid",    "profile",    "email",    "address",    "phone"  ],  "clientId": "vJ0SCKchr4XjC0xHNE8DkH6Pmlg2lkCN",  "tokenEndpointAuthMethod": "client_secret_post",  "staticRequestParameters": {    "prompt": "login",    "max_age": 10000  },  "forwardedRequestParameters": [    "login_hint"  ],  "claimsToPersist": [    "userId"  ],  "clientSecret": "***********************************************************6-OjH"}

Retrieve all Authentication Providers

GET/v1/users/authentication-providers

Returns a list of all Authentication Providers on your tenant.

Roles

adminissuermanaged-issuer

Analytics Events

USER_AUTHENTICATION_PROVIDER_RETRIEVE_LIST_STARTUSER_AUTHENTICATION_PROVIDER_RETRIEVE_LIST_SUCCESSUSER_AUTHENTICATION_PROVIDER_RETRIEVE_LIST_FAIL

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Query Parameters

limit?number

Range size of returned list.

Range1 <= value <= 1000

Default100

cursor?string

Starting point for the list of entries.

Response Body

`application/json`

curl -X GET "https://example.com/v1/users/authentication-providers"

{  "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM",  "data": [    {      "id": "983c0a86-204f-4431-9371-f5a22e506599",      "redirectUrl": "https://tenant.vii.mattr.global/v1/oauth/authentication/callback",      "url": "http://example.com",      "scope": [        "openid",        "profile",        "email",        "address",        "phone"      ],      "clientId": "vJ0SCKchr4XjC0xHNE8DkH6Pmlg2lkCN",      "tokenEndpointAuthMethod": "client_secret_post",      "staticRequestParameters": {        "prompt": "login",        "max_age": 10000      },      "forwardedRequestParameters": [        "login_hint"      ],      "claimsToPersist": [        "userId"      ],      "clientSecret": "***********************************************************6-OjH"    }  ]}

Retrieve an Authentication Provider

GET/v1/users/authentication-providers/{id}

Retrieve an existing Authentication Provider by providing its ID.

Roles

adminissuermanaged-issuer

Analytics Events

USER_AUTHENTICATION_PROVIDER_RETRIEVE_STARTUSER_AUTHENTICATION_PROVIDER_RETRIEVE_SUCCESSUSER_AUTHENTICATION_PROVIDER_RETRIEVE_FAIL

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Authentication Provider ID

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/v1/users/authentication-providers/41458e5a-9092-40b7-9a26-d4eb43c5792f"

{  "id": "983c0a86-204f-4431-9371-f5a22e506599",  "redirectUrl": "https://tenant.vii.mattr.global/v1/oauth/authentication/callback",  "url": "http://example.com",  "scope": [    "openid",    "profile",    "email",    "address",    "phone"  ],  "clientId": "vJ0SCKchr4XjC0xHNE8DkH6Pmlg2lkCN",  "tokenEndpointAuthMethod": "client_secret_post",  "staticRequestParameters": {    "prompt": "login",    "max_age": 10000  },  "forwardedRequestParameters": [    "login_hint"  ],  "claimsToPersist": [    "userId"  ],  "clientSecret": "***********************************************************6-OjH"}

Update an Authentication Provider

PUT/v1/users/authentication-providers/{id}

Updates an existing Authentication Provider by providing its ID.

Roles

adminissuermanaged-issuer

Analytics Events

USER_AUTHENTICATION_PROVIDER_UPDATE_STARTUSER_AUTHENTICATION_PROVIDER_UPDATE_SUCCESSUSER_AUTHENTICATION_PROVIDER_UPDATE_FAIL

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Authentication Provider ID

Formatuuid

Request Body

application/json

Update an Authentication Provider

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

`application/json`

curl -X PUT "https://example.com/v1/users/authentication-providers/41458e5a-9092-40b7-9a26-d4eb43c5792f" \  -H "Content-Type: application/json" \  -d '{    "clientId": "vJ0SCKchr4XjC0xHNE8DkH6Pmlg2lkCN"  }'

{  "id": "983c0a86-204f-4431-9371-f5a22e506599",  "redirectUrl": "https://tenant.vii.mattr.global/v1/oauth/authentication/callback",  "url": "http://example.com",  "scope": [    "openid",    "profile",    "email",    "address",    "phone"  ],  "clientId": "vJ0SCKchr4XjC0xHNE8DkH6Pmlg2lkCN",  "tokenEndpointAuthMethod": "client_secret_post",  "staticRequestParameters": {    "prompt": "login",    "max_age": 10000  },  "forwardedRequestParameters": [    "login_hint"  ],  "claimsToPersist": [    "userId"  ],  "clientSecret": "***********************************************************6-OjH"}

Delete an Authentication Provider

DELETE/v1/users/authentication-providers/{id}

Deletes an existing Authentication Provider by providing its ID.

Roles

adminissuermanaged-issuer

Analytics Events

USER_AUTHENTICATION_PROVIDER_DELETE_STARTUSER_AUTHENTICATION_PROVIDER_DELETE_SUCCESSUSER_AUTHENTICATION_PROVIDER_DELETE_FAIL

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Authentication Provider ID

Formatuuid

Response Body

`application/json`

curl -X DELETE "https://example.com/v1/users/authentication-providers/41458e5a-9092-40b7-9a26-d4eb43c5792f"

Empty

Configure an Authentication Provider

POST/v1/users/authentication-providers

Configures an Authentication Provider on the tenant.

The /.well-known/openid-configuration endpoint of the Authentication Provider must contain values for the authorization_endpoint, token_endpoint and scopes_supported.

Roles

adminissuermanaged-issuer

Analytics Events

USER_AUTHENTICATION_PROVIDER_CREATE_STARTUSER_AUTHENTICATION_PROVIDER_CREATE_SUCCESSUSER_AUTHENTICATION_PROVIDER_CREATE_FAIL

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Request Body

application/json

The Authentication Provider payload

TypeScript Definitions

Use the request body type in TypeScript.

scope?array<string>

OpenID scopes to use during authentication. Each scope returns a set of user attributes which are called claims. Be sure to test that right scopes are added to get all the information you need. If no scopes are provided, [openid,profile,email] are added by default. If any scopes are provided, openid must also be included in the array.

Default

[  "openid",  "profile",  "email"]

clientId*string

The client ID of the application client created on your IdP.

clientSecret*string

The client secret of the application client created on your IdP.

tokenEndpointAuthMethod?string

Authentication method for your IdP token endpoint:

client_secret_post: Your credentials are passed as parameters in the request body.
client_secret_basic (default): Your credentials are passed as a base 64 encoded token.

Default"client_secret_basic"

Value in

"client_secret_basic"
"client_secret_post"

staticRequestParameters?

Additional parameters (maximum 1000 entries allowed) that will be included in the request to your IdP. These parameters are identical for every request as defined in your configuration. An example would be setting the prompt to be login to let your IdP know it should show the login page every time. Keys must be strings. Values of top-level object keys must stringify to less than 1000 characters.

Propertiesproperties <= 1000

forwardedRequestParameters?array<>

In contrast to staticRequestParameters, you can provide dynamic parameters that are fetched uniquely for each request to make the user journey more seamless. You can forward params to your IdP like login_hint which will pass the email of the user starting the flow. Values are limited to 1000 characters each, and cannot override any core Authorize Parameters.

Default[]

claimsToPersist?array<string>

List of claims to persist from your IdP to MATTR VII. If you have attributes from the ID token (e.g. user identifier, email, etc.) that you would like persisted on MATTR VII, add them to this array. By default this array is empty, meaning no claims are persisted on MATTR VII.

Default[]

url*string

Base url for your Authentication Provider well-known endpoint:

Must be a valid URL.
Must use the HTTPS protocol.
Must not be an IP address.
Must not contain query parameters. Port and fragment parameters will be dropped.
URL must use https and have a valid public TLD.
Unicode will be converted to ASCII.

Formaturi

Response Body

`application/json`

curl -X POST "https://example.com/v1/users/authentication-providers" \  -H "Content-Type: application/json" \  -d '{    "clientId": "vJ0SCKchr4XjC0xHNE8DkH6Pmlg2lkCN"  }'

{  "id": "983c0a86-204f-4431-9371-f5a22e506599",  "redirectUrl": "https://tenant.vii.mattr.global/v1/oauth/authentication/callback",  "url": "http://example.com",  "scope": [    "openid",    "profile",    "email",    "address",    "phone"  ],  "clientId": "vJ0SCKchr4XjC0xHNE8DkH6Pmlg2lkCN",  "tokenEndpointAuthMethod": "client_secret_post",  "staticRequestParameters": {    "prompt": "login",    "max_age": 10000  },  "forwardedRequestParameters": [    "login_hint"  ],  "claimsToPersist": [    "userId"  ],  "clientSecret": "***********************************************************6-OjH"}

Retrieve all Authentication Providers

GET/v1/users/authentication-providers

Returns a list of all Authentication Providers on your tenant.

Roles

adminissuermanaged-issuer

Analytics Events

USER_AUTHENTICATION_PROVIDER_RETRIEVE_LIST_STARTUSER_AUTHENTICATION_PROVIDER_RETRIEVE_LIST_SUCCESSUSER_AUTHENTICATION_PROVIDER_RETRIEVE_LIST_FAIL

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Query Parameters

limit?number

Range size of returned list.

Range1 <= value <= 1000

Default100

cursor?string

Starting point for the list of entries.

Response Body

`application/json`

curl -X GET "https://example.com/v1/users/authentication-providers"

{  "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM",  "data": [    {      "id": "983c0a86-204f-4431-9371-f5a22e506599",      "redirectUrl": "https://tenant.vii.mattr.global/v1/oauth/authentication/callback",      "url": "http://example.com",      "scope": [        "openid",        "profile",        "email",        "address",        "phone"      ],      "clientId": "vJ0SCKchr4XjC0xHNE8DkH6Pmlg2lkCN",      "tokenEndpointAuthMethod": "client_secret_post",      "staticRequestParameters": {        "prompt": "login",        "max_age": 10000      },      "forwardedRequestParameters": [        "login_hint"      ],      "claimsToPersist": [        "userId"      ],      "clientSecret": "***********************************************************6-OjH"    }  ]}

Retrieve an Authentication Provider

GET/v1/users/authentication-providers/{id}

Retrieve an existing Authentication Provider by providing its ID.

Roles

adminissuermanaged-issuer

Analytics Events

USER_AUTHENTICATION_PROVIDER_RETRIEVE_STARTUSER_AUTHENTICATION_PROVIDER_RETRIEVE_SUCCESSUSER_AUTHENTICATION_PROVIDER_RETRIEVE_FAIL

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Authentication Provider ID

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/v1/users/authentication-providers/41458e5a-9092-40b7-9a26-d4eb43c5792f"

{  "id": "983c0a86-204f-4431-9371-f5a22e506599",  "redirectUrl": "https://tenant.vii.mattr.global/v1/oauth/authentication/callback",  "url": "http://example.com",  "scope": [    "openid",    "profile",    "email",    "address",    "phone"  ],  "clientId": "vJ0SCKchr4XjC0xHNE8DkH6Pmlg2lkCN",  "tokenEndpointAuthMethod": "client_secret_post",  "staticRequestParameters": {    "prompt": "login",    "max_age": 10000  },  "forwardedRequestParameters": [    "login_hint"  ],  "claimsToPersist": [    "userId"  ],  "clientSecret": "***********************************************************6-OjH"}

Update an Authentication Provider

PUT/v1/users/authentication-providers/{id}

Updates an existing Authentication Provider by providing its ID.

Roles

adminissuermanaged-issuer

Analytics Events

USER_AUTHENTICATION_PROVIDER_UPDATE_STARTUSER_AUTHENTICATION_PROVIDER_UPDATE_SUCCESSUSER_AUTHENTICATION_PROVIDER_UPDATE_FAIL

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Authentication Provider ID

Formatuuid

Request Body

application/json

Update an Authentication Provider

TypeScript Definitions

Use the request body type in TypeScript.

scope?array<string>

Default

[  "openid",  "profile",  "email"]

clientId*string

The client ID of the application client created on your IdP.

clientSecret?string

The client secret of the application client created on your IdP.

tokenEndpointAuthMethod?string

Authentication method for your IdP token endpoint:

client_secret_post: Your credentials are passed as parameters in the request body.
client_secret_basic (default): Your credentials are passed as a base 64 encoded token.

Default"client_secret_basic"

Value in

"client_secret_basic"
"client_secret_post"

staticRequestParameters?

Propertiesproperties <= 1000

forwardedRequestParameters?array<>

Default[]

claimsToPersist?array<string>

Default[]

Response Body

`application/json`

curl -X PUT "https://example.com/v1/users/authentication-providers/41458e5a-9092-40b7-9a26-d4eb43c5792f" \  -H "Content-Type: application/json" \  -d '{    "clientId": "vJ0SCKchr4XjC0xHNE8DkH6Pmlg2lkCN"  }'

{  "id": "983c0a86-204f-4431-9371-f5a22e506599",  "redirectUrl": "https://tenant.vii.mattr.global/v1/oauth/authentication/callback",  "url": "http://example.com",  "scope": [    "openid",    "profile",    "email",    "address",    "phone"  ],  "clientId": "vJ0SCKchr4XjC0xHNE8DkH6Pmlg2lkCN",  "tokenEndpointAuthMethod": "client_secret_post",  "staticRequestParameters": {    "prompt": "login",    "max_age": 10000  },  "forwardedRequestParameters": [    "login_hint"  ],  "claimsToPersist": [    "userId"  ],  "clientSecret": "***********************************************************6-OjH"}

Delete an Authentication Provider

DELETE/v1/users/authentication-providers/{id}

Deletes an existing Authentication Provider by providing its ID.

Roles

adminissuermanaged-issuer

Analytics Events

USER_AUTHENTICATION_PROVIDER_DELETE_STARTUSER_AUTHENTICATION_PROVIDER_DELETE_SUCCESSUSER_AUTHENTICATION_PROVIDER_DELETE_FAIL

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Authentication Provider ID

Formatuuid

Response Body

`application/json`

curl -X DELETE "https://example.com/v1/users/authentication-providers/41458e5a-9092-40b7-9a26-d4eb43c5792f"

Empty

Roles

Analytics Events

201application/json

400application/json

Roles

Analytics Events

200application/json

400application/json

Roles

Analytics Events

200application/json

400application/json

404application/json

Roles

Analytics Events

200application/json

400application/json

404application/json

Roles

Analytics Events

204

400application/json

404application/json

On this page

API Reference

Roles

Analytics Events

201application/json

400application/json

Roles

Analytics Events

200application/json

400application/json

Roles

Analytics Events

200application/json

400application/json

404application/json

Roles

Analytics Events

200application/json

400application/json

404application/json

Roles

Analytics Events

204

400application/json

404application/json

On this page

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`