Registration

The first step in using OAuth is obtaining a client_id and client_secret. To do so, please contact mesh.support@core10.io.

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.

Core Provider	Core	Scope	Description
Smiley Technologies	Smiley	core/smiley	Allows the client to make API requests to the Smiley core on behalf of an institution.
Fiserv	Premier	core/fiserv	Allows the client to make API requests to the Fiserv Communicator Open API on behalf of an institution.
Jack Henry & Associates	Silverlake, CIF2020, CoreDirector	core/jxchange	Allows the client to make API requests to the jXchange API Gateway on behalf of an institution.
CSI	Bridge	core/csi	Allows the client to make API requests to the CSI Bridge API on behalf of an institution.

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.

Error Code	Description	HTTP Status
Bad Request	The body of the request is an invalid JSON or has invalid/missing required fields.	400
Not Authenticated	Authentication to 3rd party failed.	401
Forbidden	You do not have permission to access the requested resource. Please ensure your IP is whitelisted and check your permissions.	403
Conflict	A 409 error occurs when there is a conflict with the current state of the target resource.	409
Unprocessable Entity	Unprocessable Entity indicates that the server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions.	422
Internal Server Error	Internal Server Error indicates that an unexpected condition was encountered by the server while trying to fulfill the request. This error is typically a general-purpose error, and does not necessarily indicate a specific problem with the server or the request.	500