OAuth v2.0

Start the authorization flow

get

Request to start an authorization flow. For additional details, see the OAuth v2.0 spec or the OpenID Connect §3.1.2.1.

Query parameters

response_typestringRequired

OAuth v2.0 response type. This value MUST be code for the Authorization Code Flow.

Example: code

client_idstringRequired

OAuth v2.0 client identifier previously registered at the Authorization Server. Identifies the client making the request.

Example: my-client-id-123

scopestringRequired

OpenID Connect scope values indicating the access requested.This MUST include openid as one of the space-delimited values.

Example: openid profile email

definition_idstringRequired

The ID of the template definition. Similar to scope, this defines the data requested

Example: openid profile email

redirect_uristring · uriRequired

Redirection URI to which the response will be sent. This URI MUST exactly match one of the pre-registered redirect URIs for the client.

Example: https://client.example.org/cb

statestringOptional

Opaque value used to maintain state between the request and the callback. This value is used to mitigate cross-site request forgery (CSRF) attacks. If present in the request, it MUST be returned unchanged in the response.

Example: af0ifjsldkj

Responses

200

A success response contains basic information for the client to start presenting credentials:

application/json

authorization_idstringOptional

ID of this authorization session

client_namestringOptional

Branding

client_logo_urlstringOptional

Branding

client_colorstringOptional

Branding

verification_uristringOptional

Shown as a QR code

statusstringOptional

Status of the authorization session

303

Redirect to the client's redirect_uri with OAuth error parameters as defined in RFC 6749 section-4.1.2.1.

The redirect URI MAY include the following query parameters: error (REQUIRED), error_description (OPTIONAL), state (OPTIONAL, if supplied in the request).

400

As defined in RFC 6749 section-4.1.2.1, a request with an invalid client id or redirect URI will result with a HTTP 400 response."

application/json

get

/v1/oauth2/authorization

HTTPcURLJavaScriptPython

GET /v1/oauth2/authorization?response_type=code&client_id=my-client-id-123&scope=openid+profile+email&definition_id=openid+profile+email&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb HTTP/1.1
Accept: */*

{
  "authorization_id": "b0e11610-4cf5-4797-b827-df00d99e052d",
  "client_name": "Monte Carlo Grand",
  "client_logo_url": "https://montecarlogrand.com/branding/logo.svg",
  "client_color": "#228B22",
  "verification_uri": "http://localhost:8080/mock/request",
  "status": "requested"
}

Exchange authorization code for access token

post

Exchange the authorization code received in the authorization flow for a JWT Access Token. Encode request parameters as application/x-www-form-urlencoded.

Authorizations

code-for-token-basic-auth

AuthorizationstringRequired

Security scheme used in the POST v1/oauth2/authorization/token endpoint to exchange the authorization_code for an access_token

Body

application/x-www-form-urlencoded

grant_typestring · enumRequired

Value MUST be set to authorization_code.

Possible values:

codestringRequired

The authorization code received from the authorization server.

redirect_uristringRequired

The value must match the redirect_uri sent in the authorization request.

Responses

200

Access token response

application/json

access_tokenstringRequired

access token

token_typestringRequired

Type of token. Will always be Bearer.

expires_ininteger · int32Required

Duration in seconds until the token expires.

post

/v1/oauth2/authorization/token

HTTPcURLJavaScriptPython

POST /v1/oauth2/authorization/token HTTP/1.1
Authorization: Basic username:password
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 71

"grant_type='authorization_code'&code='text'&redirect_uri='text'"

200

Access token response

{
  "access_token": "eyJraWQiOiJlWjdCa3pWSHRTXC9haXpwNnJFS1wveGIyTmM1Vkg0clRselwvdnFJcTllNUtzPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiIzMjc1ODQ0NC0yMDcxLTcwMjktNDQ0Yi0zZDA5YzJhNjI5YjMiLCJjb2duaXRvOmdyb3VwcyI6WyJJZGVudGl0eV8xX1ZlcmlmaWVyX0RldiIsIklkZW50aXR5XzFfSXNzdWVyX1NpZ25JbiIsIklkZW50aXR5XzFfSXNzdWVyX0FkbWluIiwiSWRlbnRpdHlfMV9Jc3N1ZXJfRGV2IiwiSWRlbnRpdHlfMV9TdXBlcl9EZXYiLCJJZGVudGl0eV8xX1ZlcmlmaWVyX1NpZ25JbiIsIklkZW50aXR5XzFfVmVyaWZpZXJfQWRtaW4iXSwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLmV1LXdlc3QtMS5hbWF6b25hd3MuY29tXC9ldS13ZXN0LTFfdm9HalkycGJlIiwidmVyc2lvbiI6MiwiY2xpZW50X2lkIjoiMTdkMWdyM2JkNXA0dXJtaWp0b3BsaWYyMW0iLCJvcmlnaW5fanRpIjoiNjVkZDY0YjAtNzNmYy00NzkwLTg4N2QtNjQzNjM5MjRkZWEzIiwidG9rZW5fdXNlIjoiYWNjZXNzIiwic2NvcGUiOiJhd3MuY29nbml0by5zaWduaW4udXNlci5hZG1pbiBwaG9uZSBvcGVuaWQgZW1haWwiLCJhdXRoX3RpbWUiOjE3NjUzNjI4ODQsImV4cCI6MTc2NTM3NDg1NSwiaWF0IjoxNzY1Mzc0NTU1LCJqdGkiOiIyZjZjMmM4NS01MDUyLTRmZmEtYmRkNy05YTMwZmFhZGE4OWMiLCJ1c2VybmFtZSI6IjMyNzU4NDQ0LTIwNzEtNzAyOS00NDRiLTNkMDljMmE2MjliMyJ9.unFFgEU5lsQO822CbssAR9wvTnykDH43KuAw8TDLZY2zbDNPIl_3hA0Obax2QGlmuKYrixBHojWhXf8BR3GtZPdVXkCa3Q4nHYR9tKMjw4wyStsreX1bINjYEThH6f6hcIieybIxteaI-89XPYvGvz2C-IWZK-IE_Jx06xKBFU4NiBrYlSBtbSWAvXb8jExnxkV4926WVaAZtm2kWLCYedRONrYUv4Zqa6cPU-mHnsLbXs-NZz46S8K2Fs_kfpHa9bRrCq7ytrp-t8jTfIgswOpNx5penV2mOyMYa-l2XkFZfXbRmJ4bVcJ-yedEFxwIi14EiQr9Dvwtx_CdlMLnYw",
  "token_type": "Bearer",
  "expires_in": 600
}