Authentication

Registration

The first step in using OAuth is obtaining a client_id and client_secret. To do so, please contact [email protected].

Scopes

When you register for access to the Mesh API, you will be granted a scope. The token scope is used to determine which resources you have access too. A single scope is permitted per request.

Access Tokens

To obtain an access token, you will need to make a POST request to the auth server. Your app will make requests to this endpoint directly, not through the user's browser. The auth server endpoint only supports HTTPS POST An Authorization header should be set using Basic Authentication with the client_id:client_secret base64encoded.

Request Parameters in the Header

Authorization: The client must pass its client_id and client_secret in the authorization header as client_secret_basic HTTP authorization. The authorization header string is Basic Base64Encode(client_id:client_secret). The following example is an authorization header for app client djc98u3jiedmi283eu928 with client secret abcdef01234567890, using the Base64-encoded version of the string djc98u3jiedmi283eu928:abcdef01234567890.

Authorization: Basic ZGpjOTh1M2ppZWRtaTI4M2V1OTI4OmFiY2RlZjAxMjM0NTY3ODkw

Content-Type: Must always be 'application/x-www-form-urlencoded'.

Request Parameters in the Body

grant_type: Must be set to client_credentials. You can request an access token for a custom scope from the token endpoint when, in the app client, the requested scope is enabled.

scope: A single scope is allowed per request. This scope is used to determine which resource to use for the request. If a scope is not passed in the request, all allowed scopes are returned. This will throw an error on subsequent requests.

refresh_token: To generate new access and ID tokens for a user's session, set the value of a refresh_token parameter in your /oauth2/token request to a previously-issued refresh token from the same app client.

Example Requests

Sample request:

curl --request POST 'https://auth-dev.meshtech.io/oauth2/token' \
--header 'Authorization: Basic base64encode(client_id:client_secret)' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope={{scope}}'

Sample Response:

HTTP/1.1 200 OK
Content-Type: application/json

{ 
  "access_token":"eyJz9sdfsdfsdfsd",
  "token_type":"Bearer", 
  "expires_in":3600
}

Errors

Sample Error Response:

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
  "error":"invalid_request|invalid_client|invalid_grant|unauthorized_client|unsupported_grant_type"
}

invalid_request: The request is missing a required parameter, includes an unsupported parameter value (other than unsupported_grant_type), or is otherwise malformed. For example, grant_type is refresh_token but refresh_token is not included.

invalid_client: Client authentication failed. For example, when the client includes client_id and client_secret in the authorization header, but there's no such client with that client_id and client_secret.

invalid_grant:

• Refresh token has been revoked.
• App client doesn't have read access to all attributes in the requested scope. For example, your app requests the email scope and your app client can read the email attribute, but not email_verified.

unauthorized_client: Client is not allowed for code grant flow or for refreshing tokens.

unsupported_grant_type: Returned if grant_type is anything other than authorization_code or refresh_token or client_credentials.

Response Codes

Our API responses include standard HTTP status codes, which can be found in the documentation. These codes are usually accompanied by additional data in JSON format.

• A 2xx status code indicates a successful request and may include response parameters.
• A 4xx status code indicates that there was an issue with the request, such as missing or incorrect information.
• A 5xx status code indicates an error on the endpoint service.