OAuth2 Device Flow

Authentication for headsets and other devices

This API will be available January 1, 2023. If you have any feedback on this API, please let us know.

Developers of 3rd party applications will use the OAuth2 Device Grant flow to authenticate users who log-in to MOTAR from an application running on a headset or other devices.

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

Initiate device authorization

POST https://api.motar.io/oauth/v2/device/authorize

Begin the device authorization process by providing the MOTAR Client ID and (optionally) the required scope(s).

Request Body

Name	Type	Description
client_id*	String	Your app's client ID, generated in MOTAR Studio
scope	String	Scope of the access request

200: OK Successful Response

{
    "device_code": "32df84a1-1c95-4b98-884a-906c43b3c141",
    "user_code": "BTXRVWQP",
    "verification_uri": "https://motar.io/activate"
    "verification_uri_complete": "https://motar.io/activate?BTXRVWQP"
    "expires_in": 600,
    "interval": 5
}

400: Bad Request Error Response

{
    error: "invalid_request",
    error_description: "The request is missing the client ID",
    message: "This app is not recognized",
    error_number: 4001
}

401: Unauthorized Problem with client ID

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

500: Internal Server Error Unexpected Error

{
    "error": "unavailable",
    "error_description": "Internal application error",
    "message": "We encountered an unexpected issue. Please contact MOTAR or your App administrator",
    "error_number": 5001
}

Obtain an access token

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

This endpoint provides the authorization token for devices

Request Body

Name	Type	Description
grant_type*	String	The grant type for device codes. MUST be "urn:ietf:params:grant-type:device_code"
device_code*	String	The device code provided in response to the authorize request
client_id*	String	Your app's client ID, generated in MOTAR Studio

200: OK Authorization and Refresh Token

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

400: Bad Request Authorization Error

One of the four error codes described in RFC 8628. One of "authorization_pending", "slow_down", "access_denied", "expired_token"

{
    error: "authorization_pending",
    error_description: "The authorization reuest is still pending. The end user has not yet completed the user interaction steps.",
    message: "Please enter the code in MOTAR",
    number: 4001
}

401: Unauthorized Client ID Error

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

500: Internal Server Error Unexpected Error

{
    error: "unavailable",
    error_description: "Internal application error",
    message: "We encountered an unexpected issue. Please contact MOTAR or your App administrator",
    error_number: 5001
}

Obtain a new access token from a refresh token

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

This endpoint allows the headset to retrieve a fresh access token with a refresh token and a user PIN (compared to the PIN on the user account). This flow supports the specific use case of multiple individuals using the same headset. The PIN verification confirms the correct user is initiating the session refresh.

Request Body

Name	Type	Description
refresh_token*	String	The refresh token provided in response to a successful token response
grant_type*	String	Must be "refresh_token"
client_id*	String	Your app's client ID from MOTAR Studio.
user_pin*	Number	The numeric PIN entered by the user. This should never be stored or cached on the device.

200: OK Authorization and Refresh Tokens

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

Validate a device token

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

Validates if a token is still active. Returns an error if the token needs to be refreshed or if the MOTAR session has been otherwise terminated.

Headers

Name	Type	Description
Authorization*	String	Bearer Token obtained from the token endpoint

200: OK Token valid

{
    success: true
}

401: Unauthorized Token expired

{
    error: "token_expired",
    error_description: "Token refresh required",
    message: "Your token is no longer active",
    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/device/session/validate

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

Headers

Name	Type	Description
Authorization*	string	Bearer token obtained from the token endpoint

200: OK Session valid

{
    success: true
}

401: Unauthorized Session invalid

{
    error: "session_expired",
    error_message: "New session required",
    message: "Your session is no longer valid",
    number: 4010
}

403: Forbidden Session revoked

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

Sign out of the device

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

Logs the user out of the session on the device.

Headers

Name	Type	Description
Authorization*	String	Bearer Token obtained from the token endpoint

200: OK Log out successful

{
    success: true
}