OAuth

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

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

Render OAuth Login Page

GET https://api.motar.io/oauth/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
clientId*	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	string	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.
nonce	string	An arbitrary value provided by the client that is unique to this request. This value will be returned in the token response as a way for the client to validate the request and protect against CSRF attacks.

400 Invalid response_type parameter

{
    "message": "Response type not supported",
    "number": 4002
}

401 App has not been approved.

{
    "message": "App has not been approved by MOTAR staff yet.",
    "number": 4013
}

404 No app found with supplied client ID.

{
    "message": "No app found with specified client ID.",
    "number": 4041
}

302: Found Callback to Client

OAuth login page called with the following parameters. 
HTTP response example:

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

200: OK MOTAR sign-in page

MOTAR OAuth Sign-in Page

Refresh or Generate Auth Token

POST https://api.motar.io/oauth/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".
clientId	string	Your app's client ID from MOTAR Studio.
grant_type	string	Can be "refresh_token" if refreshing an existing session or "authorization_code" if generating an auth token with a code.

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' 
}

Logout

POST https://api.motar.io/oauth/logout

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

Request Body

Name	Type	Description
refresh_token	string	Refresh token generated by OAuth flow.

200

Validate a Token

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

A simple request to validate the attached authentication token.

Headers

Name	Type	Description
Authentication	string	Auth token generated by user login.

200

{"success": true}

401 If the token has expired, you'll get the following error in the response body. Note that this error is identical to the one returned by all authenticated API routes if the authorization token is expired.

{"message": "Token refresh required", "number": 4010}

Validate a Session

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

Validates the logged-in user's session. If a user's access has been revoked by MOTAR or a 3rd party since the user logged in, this endpoint will return the appropriate error as indicated below.

Headers

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

200: OK Session is still valid.

{
    "valid": true
}

403: Forbidden Session has been invalidated.

{
    "error_code": 4037,
    "error_message": "Session revoked."
}

401: Unauthorized Token refresh required.

{
    "error_code": 4010,
    "error_message": "Token refresh required."
}