Cross River authentication and authorization
CR authentication
OAuth 2.0 is a popular protocol for authorization. This controls entry to our system and ensures that only authorized entities can access our APIs and other protected resources. The information you enter into our authentication system is confidential and can never be accessed from any other Cross River applications.
Accessing Cross River APIs
Our system authenticates machine clients and authorizes them to talk to our APIs.
Authenticating your identity
The Cross River Integration Team will provide you with a client_id and a client_secret which you should use when requesting an access token. These are the components of the HTTP request.
| HTTP component | Attribute | Description |
|---|---|---|
| Endpoint | POST /connect/token | Endpoint for retrieving an access token. |
| Header | content-type | application/x-www-form- urlencoded |
| Body | grant_type | This field will always have a value of client_credentialsSecrets aren't recoverable by CR. If you lose a secret, a new one must be generated. |
| Body | scope | A specific range of services that a user can access. - If the required scope is missing the subsequent API call will be returned as forbidden (403). - If a scope isn't specified, the token returned will contain all scopes associated with your credentials. Note: Multiple scopes can be sent in the same request by adding a space between the name of each scope. For example: 'scope=scope1 scope2 scope3' |
| Body | client_id | The unique identifier for a client. |
| Body | client_secret | An encrypted string of characters used to sign and validate ID tokens. IMPORTANT: Don’t commit your secrets into source control. |
Sample access token request in cURL
curl --location --request POST 'https://oauthtest.crbnj.net/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials' \
-d 'scope=relevant scope' \
-d 'client_id={xxx}' \
-d 'client_secret={xxx}'
Sample access token request in Postman
Successful authentication and access token returned
When you've successfully authenticated, an access_token will be returned to you. This access token allows you to send information securely as a JSON object for use in our APIs. Add this token to the header of your API calls.
IMPORTANT
Make sure to protect your token. Don’t log them. Anyone who steals your token can impersonate your client for the lifetime of the token.
| Attribute | Description |
|---|---|
access_token | A digitally signed JSON web token (JWT) sent from the oAuth server that allows access to specific Cross River resources. |
scope | A range of services that a user can access. |
expires_in | The amount of time until the token expires. - Our Integration Team will inform you of the expiration time or you can decode your access token as well. - We recommend that you retrieve a new access token a short time before the old token is set to expire. - Reuse tokens for their entire lifespan rather than getting a new token for each call to the same protected resource (API). IMPORTANT: Make sure to never decode your token on a publicly hosted website. |
token-type | Bearer token. |
Sample access token returned in Postman
If the authentication is successful, the Status code is OK.
URLs for our sandbox and production environments
- Sandbox URL: https://oauthtest.crbnj.net/connect/token
- Production URL: https://oauth.crbnj.net/connect/token
Troubleshooting
You can test the authorization and authentication into our systems with this endpoint, GET /api/SignupCard/TestOauth.
If the authentication token is valid, it will return a 200. If the authentication token isn't valid, it will return a 401.
If you can't get a bearer token and you haven't received one in the past:
- Confirm the URL.
- Check that the
client_idandclient_secretare typed correctly. They are case sensitive. - Check your
client_idandclient_secretagainst the one you received. - Make sure there are no network or allowlist issues.
Contact our Integration Team if your account is locked as a result of 3 incorrect log in attempts.
Updated 10 months ago