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.
{ error:"invalid_request", error_description:"The request is missing the client ID", message:"This app is not recognized", error_number:4001}
{ 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}
{"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
POSThttps://api.motar.io/oauth/v2/device/token
This endpoint provides the authorization token for devices
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}
{ 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}
{ error:"unavailable", error_description:"Internal application error", message:"We encountered an unexpected issue. Please contact MOTAR or your App administrator", error_number:5001}
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.
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
{ success:true}
{ error:"token_expired", error_description:"Token refresh required", message:"Your token is no longer active", number:4010}
{ error:"session_revoked", error_description:"Your session has been revoked. Please re-authenticate.", message:"Your session is no longer active", number:4037}
A simple request to validate the session associated with the attached device authentication token
Headers
{ success:true}
{ error:"session_expired", error_message:"New session required", message:"Your session is no longer valid", number:4010}
{ 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
GEThttps://api.motar.io/oauth/v2/device/logout
Logs the user out of the session on the device.
Headers
{ success:true}
Name
Type
Description
Name
Type
Description
Name
Type
Description
Name
Type
Description
Name
Type
Description
client_id*
String
Your app's client ID, generated in MOTAR Studio
scope
String
Scope of the access request
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
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.
