# Endpoints
Endpoint | Supported methods | Full URL |
---|---|---|
/authorize | GET | https://api.mpin.io/authorize |
/oidc/certs | GET | https://api.mpin.io/oidc/certs |
/oidc/token | POST | https://api.mpin.io/oidc/token |
/oidc/userinfo | GET | https://api.mpin.io/oidc/userinfo |
/.well-known/openid-configuration | GET | https://api.mpin.io/.well-known/openid-configuration |
# GET /authorize
Serves the authentication page.
# Parameters
Parameter | Type | Required | Description |
---|---|---|---|
client_id | Query | True | Client Identifier valid at the authorization server. It is generated when you create an app in the MIRACL Trust console. |
redirect_uri | Query | True | Redirection URL to which the response will be sent. This URI MUST exactly match one of the Redirect URL values specified when configuring the application in the MIRACL Trust Console. |
response_type | Query | True | Type value that determines the authorization processing flow to be used, including what parameters are returned from the endpoints used. Only code is supported |
scope | Query | True | OpenID Connect requests must contain the openid scope value. Multiple scope values may be used by creating a space-delimited (converted to + or %20 when URL encoded), case-sensitive list of scope values. For all supported scopes and a brief explanation see Scopes. |
state | Query | True | Opaque value used to maintain state between the request and the callback. Typically, Cross-Site Request Forgery (CSRF, XSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie. |
nonce | Query | False | String value used to associate a Client session with an ID Token, and to mitigate replay attacks. |
lang | Query | False | The language that you want the client to be translated in. Currently supported are en , ro , fr |
acttoken | Query | False | This is used during registration. For more information see Custom User Verification |
prerollid | Query | False | This is also a required parameter for the Custom User Verification flow. If you pass this parameter in the OIDC flow, it will prefill the user ID in the new identity screen or select the identity with this user ID if one exists |
# Request Example
curl "https://api.mpin.io/authorize?client_id=${YOUR_CLIENT_ID}&redirect_uri=${YOUR_REDIRECT_URI}&response_type=code&scope=openid+email+profile"
# GET /oidc/certs
Returns a JSON Web Key Set (JWKS) that contains the public keys that can be used to verify the signatures of tokens that you receive from your authorization server.
# Request Example
curl https://api.mpin.io/oidc/certs
# Response Example
{
"keys": [
{
"e": "AQAB",
"kid": "s1",
"kty": "RSA",
"n": "kWp2zRA23Z3vTL4uoe8kTFptxBVFunIoP4t_8TDYJrOb7D1iZNDXVeEsYKp6ppmrTZDAgd-cNOTKLd4M39WJc5FN0maTAVKJc7NxklDeKc4dMe1BGvTZNG4MpWBo-taKULlYUu0ltYJuLzOjIrTHfarucrGoRWqM0sl3z2-fv9k",
"use": "sig"
}
]
}
# POST /oidc/token
This endpoint returns the access and ID tokens. Requests to this endpoint need to be authenticated with the Client ID and Client Secret.
# Supported Endpoint Authentication
- Basic - The client ID and secret are used as a username:password pair for the HTTP Basic authentication of the request.
- POST - The client ID and secret are included in the request payload as parameters.
# Parameters
Parameter | Type | Required | Description |
---|---|---|---|
grant_type | URL encoded form | True | Only authorization_code is supported. |
code | URL encoded form | True | The value of the authorization code taken from the redirect URI. |
redirect_uri | URL encoded form | True | Must match the redirect_uri passed to the /authorize endpoint. |
client_id | URL encoded form | False | Include only if using POST authentication. |
client_secret | URL encoded form | False | Include only if using POST authentication. |
# Request Example
curl \
--request POST \
--user "${YOUR_CLIENT_ID}:${YOUR_CLIENT_SECRET}" \
--data "grant_type=authorization_code&code=${AUTHORIZATION_CODE}&redirect_uri=${YOUR_REDIRECT_URI}" \
https://api.mpin.io/oidc/token
curl \
--request POST \
--data "grant_type=authorization_code&client_id=${YOUR_CLIENT_ID}&client_secret=${YOUR_CLIENT_SECRET}&code=${AUTHORIZATION_CODE}&redirect_uri=${YOUR_REDIRECT_URL}" \
https://api.mpin.io/oidc/token
# Response Example
{
"access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InMxIn0.eyJjaWQiOiJnbGpneDJoc3FueHE3IiwiZXhwIjoxNjA3NTg4NTQ0LCJpc3MiOiJodHRwOi8vYXBpLnBsYXlncm91bmQiLCJzY3AiOlsib3BlbmlkIiwiZW1haWwiXSwic3ViIjoiNzVlZTVmYmQtNTQyNC00NjBiLWIyZGMtNjM1ZDM2NWNhMTUxQGV4YW1wbGUuY29tIn0.TFK2_P0SJfcFQQcXVrFVfC1OwEEOm70wE5lr2JR88Jejjw2rQzwDVMoa0G4wT2hDs979BXY5OpQWJcZDrDu24WcBoNnANGxAwMTDwA2C7Z2qKu_AT4zcoCTmhBaEzvvYs1vShYv95YZ5NQkmscwcFg9peaQZ9ZVSjpduMYhWcB4",
"expires_in": 900,
"id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InMxIn0.eyJhbXIiOlsidG9rZW4iXSwiYXVkIjoiZ2xqZ3gyaHNxbnhxNyIsImV4cCI6MTYwNzU4ODg0NCwiaWF0IjoxNjA3NTg3OTQ0LCJpc3MiOiJodHRwOi8vYXBpLnBsYXlncm91bmQiLCJub25jZSI6IiIsInN1YiI6Ijc1ZWU1ZmJkLTU0MjQtNDYwYi1iMmRjLTYzNWQzNjVjYTE1MUBleGFtcGxlLmNvbSJ9.JkcnvTwLpmkVFn3PHNOa4oV8ZYmCdPfU5tb8VOTLf6e8H39XbPb8rck26ECD5Nrm1CrcLGOuL8b6R2mxumPkXQK0tlbTP2hFhdZWkFn4cMewZwWDgzY7lnsWZUWOVmExJ3nfTKbLUxZ5JzwU3J4sePe6AqFud9dgIdgozvuA9lM",
"scope": "openid",
"token_type": "Bearer"
}
# GET /oidc/userinfo
Returns info about the authenticated user. This request needs to be authenticated with the access token obtained from the /oidc/token endpoint.
# Request Example
curl \
--header "Authorization: Bearer ${ACCESS_TOKEN}" \
https://api.mpin.io/oidc/userinfo
# Response Example
{
"email": "charley@example.com",
"email_verified": true,
"sub": "charley@example.com"
}
# GET /.well-known/openid-configuration
Returns OIDC metadata that can be used by clients for automatic configuration.
# Request Example
curl https://api.mpin.io/.well-known/openid-configuration
# Response Example
{
"authorization_endpoint": "https://api.mpin.io/authorize",
"claims_supported": [
"sub",
"iss",
"email",
"email_verified",
"mpin_id",
"hash_mpin_id",
"dvs_keys"
],
"id_token_signing_alg_values_supported": ["RS256", "RS384", "RS512"],
"issuer": "https://api.mpin.io",
"jwks_uri": "https://api.mpin.io/oidc/certs",
"response_types_supported": ["code"],
"scopes_supported": ["openid", "email", "dvs", "mpin_id", "hash_mpin_id"],
"subject_types_supported": ["public"],
"token_endpoint": "https://api.mpin.io/oidc/token",
"token_endpoint_auth_methods_supported": [
"client_secret_post",
"client_secret_basic"
],
"userinfo_endpoint": "https://api.mpin.io/oidc/userinfo",
"userinfo_signing_alg_values_supported": ["RS256", "RS384", "RS512"]
}
# Supported Scopes
Scope | Type | Description |
---|---|---|
openid | Standard | Must always be included. |
Standard | Requests access to the email and email_verified claims. |
|
dvs | Custom | Requests access to the dvs_keys claim. Required in order to execute DVS related operations after authentication. |
mpin_id | Custom | Requests access to the mpin_id claim. |
hash_mpin_id | Custom | Requests access to the hash_mpin_id claim. |
# Supported Claims
Claim | Type | Description |
---|---|---|
sub | Standard | Identifier for the End-User. Set to the user’s email if using default verification or the provided user ID for custom verification. Always present. |
iss | Standard | The issuer identifier for MIRACL Trust. Always present. |
Standard | End-User’s e-mail address. Present only if the email scope is included. |
|
email_verified | Standard | True if the End-User’s e-mail address has been verified; otherwise false. Present only if the email scope is included. |
mpin_id | Custom | Present only if the mpin_id scope is included. |
hash_mpin_id | Custom | Present only if the hash_mpin_id scope is included. |
dvs_keys | Custom | Present only if the dvs scope is included. |