OAuth2 with PKCE

Coming Soon! If you have any feedback on this API, please let us know.

Reminder: new apps connecting to MOTAR should use PKCE flow, as it offers more security. MOTAR may deprecate Implicit flow in the future.

Reminder: if you are using an app/client ID in sandbox, you must use sandbox.motar.io as the endpoint for your requests.

Render OAuth Login Page

GET https://api.motar.io/oauth/v2/signin

This endpoint renders the OAuth login page. This page can be displayed in a browser or an app's webview. Your app should be configured to accept a redirect from the OAuth screen and should capture the resulting tokens to maintain the logged-in user's session.

Query Parameters

Name	Type	Description
client_id*	string	Your app's client ID, generated in MOTAR Studio.
response_type*	string	Determines what auth flow to use. Can be "code" or "implicit". "Code" auth flow will generate an auth-code that can be used to retrieve an auth token, while "implicit" will generate an auth and refresh token directly.
redirect_uri*	string	After logging in, the user will be redirected to this URI. Must be registered for your app in MOTAR Studio beforehand.
state*	string	This will be passed through the auth flow and to the redirect URI. Can be any arbitrary string.
app_login*	boolean	Determines whether or not the OAuth screen should include the "Login via MOTAR App" button. Set to "true" if your client is an app to allow users to login if they have the MOTAR app.
code_challenge*	string	A base64-encoded SHA256 hash of the code_verifier later used to retrieve the token. The code_verifier must be a string between 43 and 128 characters in length matching the regex /^([A-Za-z0-9.-_~]){43,128}$/
code_challenge_method*	string	The method used to generate the code challenge. MUST BE "S256".
nonce	string	A value provided by the calling application that can uniquely identify the user but whose value is never reused.

400 Authorization Error

One of the four error codes described in RFC 6749: invalid request, invalid grant, unauthorized client, unsupported grant type, invalid scope.

{
    error: "invalid_scope",
    error_description: "An unrecognized scope was requested",
    message: "This app is requesting invalid permissions",
    number: 4002
}

401 Client ID error

No app found with supplied client ID or the app has not been approved

{
    error: "invalid_client",
    error_description: "No app found with specified client ID or the app has not been approved",
    message: "This app is not recognized or is not approved for use on MOTAR",
    number: 4013
}

406 Code challenge method not supported

{
    error: "code_challenge_method_unsupported",
    error_description: "Code challenge method not supported. Only S256 is supported.",
    message: "Error in the authorization request, please contact your application administrator.",
    number: 4016
}

302: Found Redirect to Callback URL

If login is successful and user approves
HTTP response example:

https://your.url/oauth2/callback?code=eyyAA2mO7Y&state=l490OVFUknVh6

200: OK Display MOTAR sign-in page

{
    // Response
}

Refresh or Generate Auth Token

POST https://api.motar.io/oauth/v2/token

Generates an auth token with a code or refreshes a session using a refresh token.

Request Body

Name	Type	Description
refresh_token	string	Refresh token generated by the OAuth flow. Required if using grant_type "refresh_token"
code	string	An authorization code generated from the OAuth flow. Required if using grant_type "authorization_code".
client_secret	string	Your app's client secret from MOTAR studio required for grant_type "refresh_token".
client_id*	string	Your app's client ID from MOTAR Studio.
grant_type*	string	Must be either "refresh_token" if refreshing an existing session or "authorization_code" if generating an auth token with a code.
code_verifier	string	The code verifier used to generate the code challenge value in the authorization request. Required for grant_type "authorization_code". The code_verifier string is between 43 and 128 characters in length matching the regex /^([A-Za-z0-9.-_~]){43,128}$/

200 If using grant_type "refresh_token" a JSON structure is returned.

{
  access_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbiI6Ijg5MTNhNjNmNGEzNGU4ZTZmOGI0Zjg4MjY4ZWM1OGM3NWQwOThiNTYyYWFlNmJjMWZhM2ZhNjBkN2M4YWY5MTIxMThiZWNjNDdhY2I0NzNmNmFhYWNhNjBmMjdjNGY0OGJjNWVlYjE5NGNkMGI2MmI2YTU4MTRhNjRmMjg1OTRkNTVmNjQ0NmE0ZGFhODUxY2RlODFjMWVmMzhiZTBlOTYyMyQxMDI4YTQ4MzVmMjlmZTM4M2E1YzhlZjM0M2E3ZGNhMSIsImlhdCI6MTU0ODk2MTM3NywiZXhwIjoxNTQ4OTYxNDA3LCJhdWQiOiJpb2stY2lkLTYzYTM1ZTZkNjI5NTUyMDFlNjIxMWE4MzU3YTFlMWVhOTNmZmU1ZDRmOTA0MzBkOSIsImlzcyI6InNzby5pb2tpZHMubmV0Iiwic3ViIjoiODkxM2E2M2Y0YTM0ZThlNmY4YjRmODgyNjhlYzU4Yzc1ZDA5OGI1NjJhYWU2YmMxZmEzZmE2MGQ3YzhhZjkxMjExOGJlY2M0N2FjYjQ3M2Y2YWFhY2E2MGYyN2M0ZjQ4YmM1ZWViMTk0Y2QwYjYyYjZhNTgxNGE2NGYyODU5NGQ1NWY2NDQ2YTRkYWE4NTFjZGU4MWMxZWYzOGJlMGU5NjIzJDEwMjhhNDgzNWYyOWZlMzgzYTVjOGVmMzQzYTdkY2ExIiwianRpIjoiZTcxZDFiZmY1Mzc0MjE3YWMxMDUxMWExZmZkN2Q0NDk0NTMyMmRjMDY5MGYxODNmMDMxZjE3MDRmZDJmYzc2YiJ9.kdVJzH0Tlg12MWq5EB9Hb9M0zGv8JnzJYLAGoDnJsBg',
  refresh_token: '99d26e731f5a651b19c2134f6d09bd4c45da73600c161877d3bc045265e8951a',
  expires_in: 3600,
  token_type: 'Bearer',
  id_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbiI6Ijg5MTNhNjNmNGEzNGU4ZTZmOGI0Zjg4MjY4ZWM1OGM3NWQwOThiNTYyYWFlNmJjMWZhM2ZhNjBkN2M4YWY5MTIxMThiZWNjNDdhY2I0NzNmNmFhYWNhNjBmMjdjNGY0OGJjNWVlYjE5NGNkMGI2MmI2YTU4MTRhNjRmMjg1OTRkNTVmNjQ0NmE0ZGFhODUxY2RlODFjMWVmMzhiZTBlOTYyMyQxMDI4YTQ4MzVmMjlmZTM4M2E1YzhlZjM0M2E3ZGNhMSIsImlhdCI6MTU0ODk2MTM3NywiZXhwIjoxNTQ4OTYxNDA3LCJhdWQiOiJpb2stY2lkLTYzYTM1ZTZkNjI5NTUyMDFlNjIxMWE4MzU3YTFlMWVhOTNmZmU1ZDRmOTA0MzBkOSIsImlzcyI6InNzby5pb2tpZHMubmV0Iiwic3ViIjoiODkxM2E2M2Y0YTM0ZThlNmY4YjRmODgyNjhlYzU4Yzc1ZDA5OGI1NjJhYWU2YmMxZmEzZmE2MGQ3YzhhZjkxMjExOGJlY2M0N2FjYjQ3M2Y2YWFhY2E2MGYyN2M0ZjQ4YmM1ZWViMTk0Y2QwYjYyYjZhNTgxNGE2NGYyODU5NGQ1NWY2NDQ2YTRkYWE4NTFjZGU4MWMxZWYzOGJlMGU5NjIzJDEwMjhhNDgzNWYyOWZlMzgzYTVjOGVmMzQzYTdkY2ExIiwianRpIjoiZTcxZDFiZmY1Mzc0MjE3YWMxMDUxMWExZmZkN2Q0NDk0NTMyMmRjMDY5MGYxODNmMDMxZjE3MDRmZDJmYzc2YiJ9.kdVJzH0Tlg12MWq5EB9Hb9M0zGv8JnzJYLAGoDnJsBg'
}

Logout

GET https://api.motar.io/oauth/v2/logout

Logs out a user that has been logged in via OAuth screen.

Request Body

Name	Type	Description
Authorization*	String	Bearer token generated by user login

200 Success

{
    success: true
}

Validate a Token

GET https://api.motar.io/oauth/v2/token/validate

A simple request to validate the attached authentication token.

Headers

Name	Type	Description
Authentication*	string	Bearer token generated by user login.

200 Token is valid

{
    success: true
}

401 Token expired

{
    error: "token_expired",
    error_descripton: "Token refresh required", 
    message: "Your token is no longer valid",
    number: 4010
}

403: Forbidden Session revoked

{
    error: "session_revoked",
    error_description: "Your session has been revoked. Please re-authenticate.",
    message: "Your session is no longer active",
    number: 4037
}

Validate a Session

GET https://api.motar.io/oauth/v2/session/validate

A simple request to validate the session associated with the attached authentication token

Headers

Name	Type	Description
Authorization*	string	Bearer token generated by user login

200: OK Session is valid

{
    success: true
}

401: Unauthorized Session expired

{
    error: "session_expired",
    error_descripton: "Session refresh required", 
    message: "Your session is no longer valid",
    number: 4010
}

403: Forbidden Session revoked

{
    error: "session_revoked",
    error_description: "Your session has been revoked. Please re-authenticate.",
    message: "Your session is no longer active",
    number: 4037
}