MIRACL Trust OIDC API

# 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.
prerollid Query False 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.
email 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.
email 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.