Properly authenticate your requests when integrating with Ryder's Transportation & Logistics APIs. This guide covers the authentication methods our APIs support, including API key verification for legacy APIs and OAuth 2.0 authentication for newer APIs protected by Azure API Management and Okta.
Some of Ryder's legacy APIs use API key verification for authentication. To access these APIs, you'll need to include your API subscription key in the request headers. API subscription keys can be obtained from your Ryder account dashboard.
When making requests to legacy APIs, include your API subscription key in the `Ocp-Apim-Subscription-Key` header:
GET /api/legacy/endpoint HTTP/1.1Ocp-Apim-Subscription-Key: your_subscription_key
Ryder's newer APIs are protected by Azure API Management and Okta, utilizing the OAuth 2.0 protocol for authentication. OAuth 2.0 provides a secure way to grant limited access to your Ryder account data without sharing your credentials. The two main OAuth 2.0 grant types supported by our APIs are Client Credentials and Authorization Code.
The Client Credentials grant is suitable for server-to-server communication where your application needs to access Ryder APIs on its own behalf, without user interaction. To authenticate using the Client Credentials grant:
1. Obtain a client ID and client secret from your Ryder developer account.
2. Make a POST request to the Okta token endpoint with the following parameters:
- `grant_type`: Set to `client_credentials`.
- `client_id`: Your client ID.
- `client_secret`: Your client secret.
- `scope`: The desired scope(s) for the access token.
Example request:
POST /oauth2/default/v1/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Ocp-Apim-Subscription-Key: your_subscription_key
grant_type=client_credentials&client_id=your_client_id&client_secret=your_client_secret&scope=api:read
3. If the request is successful, Okta will respond with an access token that you can use to authenticate subsequent API requests.
The Authorization Code grant is used when your application needs to access Ryder APIs on behalf of a user. This grant type involves redirecting the user to an Okta-hosted login page, where they can grant your application access to their Ryder account data. To authenticate using the Authorization Code grant:
1. Redirect the user to the Okta authorization endpoint with the following parameters:
- `client_id`: Your client ID.
- `response_type`: Set to `code`.
- `redirect_uri`: The URL where Okta should redirect the user after authentication.
- `scope`: The desired scope(s) for the access token.
- `state`: An optional parameter to prevent CSRF attacks.
2. After the user logs in and grants access, Okta will redirect them back to your specified `redirect_uri` with an authorization code.
3. Exchange the authorization code for an access token by making a POST request to the Okta token endpoint with the following parameters:
- `grant_type`: Set to `authorization_code`.
- `client_id`: Your client ID.
- `client_secret`: Your client secret.
- `redirect_uri`: The same `redirect_uri` used in step 1.
- `code`: The authorization code received in step 2.
Example request:
POST /oauth2/default/v1/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Ocp-Apim-Subscription-Key: your_subscription_key
grant_type=authorization_code&client_id=your_client_id&client_secret=your_client_secret&redirect_uri=your_redirect_uri&code=your_authorization_code
4. If the request is successful, Okta will respond with an access token that you can use to authenticate subsequent API requests on behalf of the user.
Once you have obtained an access token using either the Client Credentials or Authorization Code grant, include it in the `Authorization` header of your API requests, along with your API subscription key in the `Ocp-Apim-Subscription-Key` header:
GET /api/protected/endpoint HTTP/1.1
Authorization: Bearer your_access_token
Ocp-Apim-Subscription-Key: your_subscription_key