API Reference
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.
The /.well-known/openid-configuration endpoint of the Authentication Provider must contain values for the authorization_endpoint, token_endpoint and scopes_supported.
Roles
Analytics Events
bearerAuthAuthorizationBearer <token>The Authentication Provider payload
application/json- body
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.
[ "openid", "profile", "email"]clientId*stringThe client ID of the application client created on your IdP.
clientSecret*stringThe client secret of the application client created on your IdP.
tokenEndpointAuthMethod?stringAuthentication 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"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.
properties <= 1000forwardedRequestParameters?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.
[]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.
[]url*stringBase 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.
uriAuthentication Provider configured
application/json- response
id?stringUnique identifier for the configured authentication provider. This identifier can be used to retrieve, update or remove the authentication provider configuration.
uuidredirectUrl?stringYou will need to add this URL to your IdP's allowed redirects list, to enable it to redirect the user back to the wallet upon successful authentication with your IdP. If you are using Auth0 as your identity provider, this guide shows how to add callback URLs. For others, consult your provider for instructions on adding callback URLs.
uriurl?stringBase url for your Authentication Provider well-known endpoint.
uriscope?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.
[ "openid", "profile", "email"]clientId*stringThe client ID of the application client created on your IdP.
clientSecret*stringYour authentication provider client secret will be masked in the response without revealing the actual secret. If the secret is less than 20 characters it will be completely masked, and if it is over 20 only the last 5 characters are revealed.
tokenEndpointAuthMethod?stringAuthentication 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"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.
properties <= 1000forwardedRequestParameters?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.
[]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.
[]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
Returns a list of all Authentication Providers on your tenant.
Roles
Analytics Events
bearerAuthAuthorizationBearer <token>limit?numberRange size of returned list.
1 <= value <= 1000100cursor?stringStarting point for the list of entries.
Authentication Providers retrieved
application/json- response
nextCursor?stringStarting point for next cursor to use in a page
data?array<>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
Retrieve an existing Authentication Provider by providing its ID.
Roles
Analytics Events
bearerAuthAuthorizationBearer <token>id*stringAuthentication Provider ID
uuidAuthentication Provider retrieved
application/json- response
id?stringUnique identifier for the configured authentication provider. This identifier can be used to retrieve, update or remove the authentication provider configuration.
uuidredirectUrl?stringYou will need to add this URL to your IdP's allowed redirects list, to enable it to redirect the user back to the wallet upon successful authentication with your IdP. If you are using Auth0 as your identity provider, this guide shows how to add callback URLs. For others, consult your provider for instructions on adding callback URLs.
uriurl?stringBase url for your Authentication Provider well-known endpoint.
uriscope?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.
[ "openid", "profile", "email"]clientId*stringThe client ID of the application client created on your IdP.
clientSecret*stringYour authentication provider client secret will be masked in the response without revealing the actual secret. If the secret is less than 20 characters it will be completely masked, and if it is over 20 only the last 5 characters are revealed.
tokenEndpointAuthMethod?stringAuthentication 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"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.
properties <= 1000forwardedRequestParameters?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.
[]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.
[]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
Updates an existing Authentication Provider by providing its ID.
Roles
Analytics Events
bearerAuthAuthorizationBearer <token>id*stringAuthentication Provider ID
uuidUpdate an Authentication Provider
application/json- body
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.
[ "openid", "profile", "email"]clientId*stringThe client ID of the application client created on your IdP.
clientSecret?stringThe client secret of the application client created on your IdP.
tokenEndpointAuthMethod?stringAuthentication 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"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.
properties <= 1000forwardedRequestParameters?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.
[]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.
[]Authentication Provider updated
application/json- response
id?stringUnique identifier for the configured authentication provider. This identifier can be used to retrieve, update or remove the authentication provider configuration.
uuidredirectUrl?stringYou will need to add this URL to your IdP's allowed redirects list, to enable it to redirect the user back to the wallet upon successful authentication with your IdP. If you are using Auth0 as your identity provider, this guide shows how to add callback URLs. For others, consult your provider for instructions on adding callback URLs.
uriurl?stringBase url for your Authentication Provider well-known endpoint.
uriscope?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.
[ "openid", "profile", "email"]clientId*stringThe client ID of the application client created on your IdP.
clientSecret*stringYour authentication provider client secret will be masked in the response without revealing the actual secret. If the secret is less than 20 characters it will be completely masked, and if it is over 20 only the last 5 characters are revealed.
tokenEndpointAuthMethod?stringAuthentication 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"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.
properties <= 1000forwardedRequestParameters?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.
[]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.
[]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
Deletes an existing Authentication Provider by providing its ID.
Roles
Analytics Events
bearerAuthAuthorizationBearer <token>id*stringAuthentication Provider ID
uuidAuthentication Provider deleted
curl -X DELETE "https://example.com/v1/users/authentication-providers/41458e5a-9092-40b7-9a26-d4eb43c5792f"How would you rate this page?
Last updated on