API Reference
Configure an Authentication Provider
Configure an Authentication Provider
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.
ℹ️ Note: Only one authentication provider can be configured on a tenant.
The /.well-known/openid-configuration
endpoint of the Authentication Provider must contain values for the authorization_endpoint
, token_endpoint
and scopes_supported
.
Analytic events
- USER_AUTHENTICATION_PROVIDER_CREATE_START
- USER_AUTHENTICATION_PROVIDER_CREATE_SUCCESS
- USER_AUTHENTICATION_PROVIDER_CREATE_FAIL
/v1/users/authentication-providers
In: header
The Authentication Provider payload
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.
["openid","profile","email"]
The client ID of the application client created on your IdP.
The client secret of the application client created on your IdP.
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.
"client_secret_basic"
"client_secret_basic" | "client_secret_post"
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.
properties <= 1000
Empty Object
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.
[]
List of claims to persist from your IdP to MATTR VII. If you have attributes from the ID token (e.g. email, picture, 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.
[]
curl -X POST "https://example.vii.au01.mattr.global/v1/users/authentication-providers" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example-university.au.auth0.com", "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",
"clientSecret": "***********************************************************6-OjH",
"tokenEndpointAuthMethod": "client_secret_post",
"staticRequestParameters": {
"prompt": "login",
"max_age": 10000
},
"forwardedRequestParameters": [
"login_hint"
],
"claimsToPersist": [
"first_name",
"last_name",
"email"
]
}
{
"code": "string",
"message": "string",
"details": [
{
"value": "string",
"msg": "Invalid value",
"param": "id",
"location": "body"
}
]
}
Retrieve all Authentication Providers
Retrieve all Authentication Providers
Returns a list of all Authentication Providers on your tenant.
Analytic events
- USER_AUTHENTICATION_PROVIDER_RETRIEVE_LIST_START
- USER_AUTHENTICATION_PROVIDER_RETRIEVE_LIST_SUCCESS
- USER_AUTHENTICATION_PROVIDER_RETRIEVE_LIST_FAIL
/v1/users/authentication-providers
In: header
Query Parameters
Range size of returned list.
100
1 <= value <= 1000
Starting point for the list of entries.
curl -X GET "https://example.vii.au01.mattr.global/v1/users/authentication-providers?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h"
{
"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",
"clientSecret": "***********************************************************6-OjH",
"tokenEndpointAuthMethod": "client_secret_post",
"staticRequestParameters": {
"prompt": "login",
"max_age": 10000
},
"forwardedRequestParameters": [
"login_hint"
],
"claimsToPersist": [
"first_name",
"last_name",
"email"
]
}
]
}
{
"code": "string",
"message": "string",
"details": [
{
"value": "string",
"msg": "Invalid value",
"param": "id",
"location": "body"
}
]
}
Retrieve an Authentication Provider
Retrieve an Authentication Provider
Retrieve an existing Authentication Provider by providing its ID.
Analytic events
- USER_AUTHENTICATION_PROVIDER_RETRIEVE_START
- USER_AUTHENTICATION_PROVIDER_RETRIEVE_SUCCESS
- USER_AUTHENTICATION_PROVIDER_RETRIEVE_FAIL
/v1/users/authentication-providers/{id}
In: header
Path Parameters
Authentication Provider ID
uuid
curl -X GET "https://example.vii.au01.mattr.global/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",
"clientSecret": "***********************************************************6-OjH",
"tokenEndpointAuthMethod": "client_secret_post",
"staticRequestParameters": {
"prompt": "login",
"max_age": 10000
},
"forwardedRequestParameters": [
"login_hint"
],
"claimsToPersist": [
"first_name",
"last_name",
"email"
]
}
{
"code": "string",
"message": "string",
"details": [
{
"value": "string",
"msg": "Invalid value",
"param": "id",
"location": "body"
}
]
}
{
"code": "string",
"message": "string",
"details": [
{
"value": "string",
"msg": "Invalid value",
"param": "id",
"location": "body"
}
]
}
Update an Authentication Provider
Update an Authentication Provider
Updates an existing Authentication Provider by providing its ID.
Analytic events
- USER_AUTHENTICATION_PROVIDER_UPDATE_START
- USER_AUTHENTICATION_PROVIDER_UPDATE_SUCCESS
- USER_AUTHENTICATION_PROVIDER_UPDATE_FAIL
/v1/users/authentication-providers/{id}
In: header
Path Parameters
Authentication Provider ID
uuid
Update an Authentication Provider
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.
["openid","profile","email"]
The client ID of the application client created on your IdP.
The client secret of the application client created on your IdP.
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.
"client_secret_basic"
"client_secret_basic" | "client_secret_post"
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.
properties <= 1000
Empty Object
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.
[]
List of claims to persist from your IdP to MATTR VII. If you have attributes from the ID token (e.g. email, picture, 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.
[]
curl -X PUT "https://example.vii.au01.mattr.global/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",
"clientSecret": "***********************************************************6-OjH",
"tokenEndpointAuthMethod": "client_secret_post",
"staticRequestParameters": {
"prompt": "login",
"max_age": 10000
},
"forwardedRequestParameters": [
"login_hint"
],
"claimsToPersist": [
"first_name",
"last_name",
"email"
]
}
{
"code": "string",
"message": "string",
"details": [
{
"value": "string",
"msg": "Invalid value",
"param": "id",
"location": "body"
}
]
}
{
"code": "string",
"message": "string",
"details": [
{
"value": "string",
"msg": "Invalid value",
"param": "id",
"location": "body"
}
]
}
Delete an Authentication Provider
Delete an Authentication Provider
Deletes an existing Authentication Provider by providing its ID.
Analytic events
- USER_AUTHENTICATION_PROVIDER_DELETE_START
- USER_AUTHENTICATION_PROVIDER_DELETE_SUCCESS
- USER_AUTHENTICATION_PROVIDER_DELETE_FAIL
/v1/users/authentication-providers/{id}
In: header
Path Parameters
Authentication Provider ID
uuid
curl -X DELETE "https://example.vii.au01.mattr.global/v1/users/authentication-providers/41458e5a-9092-40b7-9a26-d4eb43c5792f"
{
"code": "string",
"message": "string",
"details": [
{
"value": "string",
"msg": "Invalid value",
"param": "id",
"location": "body"
}
]
}
{
"code": "string",
"message": "string",
"details": [
{
"value": "string",
"msg": "Invalid value",
"param": "id",
"location": "body"
}
]
}
How would you rate this page?