Authentication

OpenPath API requests use JSON Web Tokens (JWTs) sent in the Authorization header. Before calling a protected endpoint, exchange your OpenPath API Login ID and Transaction Key for an access token.

Keep your Transaction Key, access token, and refresh token secret. Do not place them in browser or mobile client code, commit them to source control, or include them in logs.

How it works

1. Request a token with your API Login ID and Transaction Key.
2. Send the returned JWT as a bearer token on protected API requests.
3. Refresh the token before it expires, replacing both stored tokens with the new values.
4. Revoke the refresh token when the integration is decommissioned or a secret may have been exposed.

The access token is valid for 60 minutes. The refresh token is valid for 7 days and is single-use: a successful refresh revokes the previous refresh token and its associated access token. Always use the newly returned pair after refreshing.

Get an access token

Send your API Login ID and Transaction Key to the token endpoint. This request does not require an Authorization header.

POST https://api.openpath.io/v5/Authorization/get-oauth-token
Content-Type: application/json

{
  "api_login_id": "YOUR_API_LOGIN_ID",
  "transaction_key": "YOUR_TRANSACTION_KEY"
}

curl --request POST 'https://api.openpath.io/v5/Authorization/get-oauth-token' \
  --header 'Content-Type: application/json' \
  --data '{
    "api_login_id": "YOUR_API_LOGIN_ID",
    "transaction_key": "YOUR_TRANSACTION_KEY"
  }'

On success, the API returns an access token, a refresh token, and UTC timestamps for when the token was issued and will expire.

{
  "timestamp": "2026-09-02T01:00:00Z",
  "token": "eyJhbGciOi...",
  "refresh_token": "0f3c6ea9-...",
  "expires": "2026-09-02T02:00:00Z"
}

Store token, refresh_token, and expires securely. Use expires to renew the credentials before an authenticated request fails.

Authenticate API requests

Include the access token in the HTTP Authorization header using the Bearer scheme:

Authorization: Bearer YOUR_ACCESS_TOKEN

For example, a protected endpoint request has the following shape:

curl --request POST 'https://api.openpath.io/v5/Transaction/charge' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{ ... }'

Do not send the Transaction Key on normal API calls. It is only used to obtain an access token.

Refresh an access token

Refresh the access token before it expires, or after receiving an authentication failure caused by expiration. Send only the current refresh token:

POST https://api.openpath.io/v5/Authorization/refresh-oauth-token
Content-Type: application/json

{
  "refresh_token": "YOUR_REFRESH_TOKEN"
}

The response has the same shape as the original token response. Persist the new token and refresh_token together before making another request. The prior refresh token cannot be used again, and the prior access token is no longer valid.

If the refresh token has expired, been revoked, or was already used, request a new token with the API Login ID and Transaction Key.

Revoke credentials

To end a session or respond to a suspected credential exposure, revoke the current refresh token:

POST https://api.openpath.io/v5/Authorization/revoke-oauth-token
Content-Type: application/json

{
  "refresh_token": "YOUR_REFRESH_TOKEN"
}

Revocation prevents the refresh token from being used again and invalidates the access token that was issued with it. Obtain a new token pair before resuming protected API requests.

Handle authentication errors

• 400 Bad Request: A required request field is missing or invalid. Check the JSON field names and ensure the values are non-empty.
• 401 Unauthorized: Credentials are invalid, or the access or refresh token is expired, revoked, or invalid. Obtain a new token with valid credentials, or refresh with the current unexpired refresh token.
• 403 Forbidden: The token is valid but the account is not permitted to perform the requested operation. Confirm that the API account has access to the endpoint and relevant OpenPath resources.

Integration recommendations

• Keep credentials in a server-side secret store or environment variables.
• Cache the access token until shortly before expires; do not request a new token for every API call.
• Ensure only one worker refreshes a token pair at a time. Because refresh tokens rotate, concurrent refreshes can cause one worker to use a revoked token.
• Redact the Authorization header, Transaction Key, and refresh token from logs, error reports, and support tickets.
• Use HTTPS for every request to the OpenPath API.