Authentication

The Spark Commodities API uses OAuth 2.0 for authentication. This guide walks you through the authentication process in three simple steps.

Important

All API requests must be made over HTTPS.

Overview

Authentication follows this workflow:

1. Create OAuth2 credentials (one-time setup)
2. Generate an access token (use credentials to get a token)
3. Make authenticated requests (include token in API calls)

Step 1: Create OAuth2 Credentials

Get Your Credentials

Visit the Spark API Management Portal to create an OAuth2 client. This is a one-time setup that gives you:

• Client ID - Your application's unique identifier
• Client Secret - Your application's password

You can download these credentials as a CSV file.

Important Notes

Security

Keep your Client ID and Client Secret confidential. Never expose them in client-side code or public repositories.

Organization Ownership

OAuth2 clients belong to your organization, not individual users. This makes it easier to manage access when team members change.

If You Have Lost Your Credentials File

You can reset by clicking on the reset icon on the client via the Manage your OAuth2 clients table. Then, click on the circular arrow icon "Reset client secret" to download new credentials.

Step 2: Generate an Access Token

Use your OAuth2 credentials to obtain an access token that authenticates your API requests.

Understanding Tokens

• Access Token: Valid for 3 hours, used to authenticate API requests
• Refresh Token: Long-lived token used to get new access tokens without re-authenticating

How to Request

Send a POST request to the token endpoint. You can choose between two formats:

Option 1: JSON Format (Recommended)

HTTP Headers:

• Content-Type: application/json
• Accept: application/json

Request Body:

{
    "grantType": "clientCredentials",
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret"
}

Response (HTTP 201):

{
    "accessToken": "...",
    "refreshToken": "...",
    "tokenType": "Bearer",
    "expiresIn": 1800
}

Option 2: Form-Encoded Format

HTTP Headers:

• Content-Type: application/x-www-form-urlencoded
• Accept: application/json
• Authorization: Basic <base64(client_id:client_secret)> (optional - see note below)

Request Body:

grant_type=client_credentials

Response (HTTP 201):

{
    "access_token": "...",
    "refresh_token": "...",
    "token_type": "Bearer",
    "expires_in": 1800
}

Authentication Methods

You can provide credentials in two ways:

1. In the request body - Include clientId and clientSecret (JSON) or client_id and client_secret (form-encoded)
2. In the Authorization header - Use Basic authentication with base64-encoded client_id:client_secret

If you use the Authorization header, you don't need to include credentials in the body.

Request Examples

Form-encoded request:

POST https://api.sparkcommodities.com/oauth/token/ HTTP/1.1
HOST: my-server
Content-Type: application/x-www-form-urlencoded
Content-Length: 72
Accept: application/json
Authorization: Basic <base64("{{client_id}}:{{client_secret}}")>
 
grant_type=client_credentials

JSON request:

POST https://api.sparkcommodities.com/oauth/token/ HTTP/1.1
HOST: my-server
Content-Type: application/json
Accept: application/json
 
{{
    "grantType": "clientCredentials",
    "clientId": "{{my-client-id}}",
    "clientSecret": "{{my-client-secret}}",
}}

Step 3: Refresh Your Access Token

When your access token expires, use your refresh token to get a new access token without re-entering credentials.

How to Refresh

Send a POST request with your refresh token. Choose your preferred format:

JSON Format (Recommended)

HTTP Headers:

• Content-Type: application/json
• Accept: application/json

Request Body:

{
    "grantType": "refreshToken",
    "refreshToken": "your-refresh-token"
}

Response (HTTP 201):

{
    "accessToken": "...",
    "refreshToken": "...",
    "tokenType": "Bearer",
    "expiresIn": 1800
}

Form-Encoded Format

HTTP Headers:

• Content-Type: application/x-www-form-urlencoded
• Accept: application/json

Request Body:

grant_type=refresh_token&refresh_token=your-refresh-token

Response (HTTP 201):

{
    "access_token": "...",
    "refresh_token": "...",
    "token_type": "Bearer",
    "expires_in": 1800
}

Refresh Token Lifecycle

The refreshToken (or refresh_token) field in the response may be null if your refresh token is about to expire. In this case, you'll need to re-authenticate using your client credentials.

Refresh Examples

Form-encoded request:

POST https://api.sparkcommodities.com/oauth/token/ HTTP/1.1
HOST: my-server
Content-Type: application/x-www-form-urlencoded
Content-Length: <length>
Accept: application/json
 
grant_type=refresh_token&refresh_token=<refresh_token>

JSON request:

POST https://api.sparkcommodities.com/oauth/token/ HTTP/1.1
HOST: my-server
Content-Type: application/json
Accept: application/json
 
{{
    "grantType": "refreshToken",
    "refreshToken": "<refresh-token>"
}}

Making Authenticated API Requests

Once you have an access token, include it in the Authorization header of all API requests:

GET https://api.sparkcommodities.com/v1.0/contracts/ HTTP/1.1
HOST: my-server
Accept: application/json
Authorization: Bearer <access_token>

Authentication Header Format

Authorization: Bearer <your-access-token>

Replace <your-access-token> with the token you received from the token endpoint.