Authentication

The Consignly API uses OAuth 2.0 for authentication. All API requests must include a valid access token in the Authorization header.

Creating a Custom App

Before authenticating with the API, a custom app must be created in the Consignly account:

1. Log in to the Consignly account
2. Navigate to App Integrations > Custom Apps
3. Click the Plus button to open New Custom App
4. Configure the app settings:
   • App Name: A descriptive name for the integration
   • Description: Short sentence on what the integration does
   • Grant Type: Either Authorisation Code or Client Credentials (refer to OAuth 2.0 Flows below for details)
   • Redirect URI: Required for Authorization Code flow (use https://localhost/callback for testing)
5. Click Create Custom App to save
6. Generate the Client Secret and note this securely alongside the Client ID

Important: The Client Secret must be stored securely. It cannot be retrieved after initial creation.

OAuth 2.0 Flows

Consignly supports two OAuth 2.0 authentication flows:

Client Credentials Flow

This flow is used for server-to-server integrations where no user interaction is required.

Request:

curl -X POST https://identity.consignlyhq.com/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=CLIENT_ID" \
  -d "client_secret=CLIENT_SECRET"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Authorization Code Flow

This flow is used for applications that act on behalf of a user.

Step 1: Redirect to Authorization

Redirect the user to the Consignly authorization endpoint:

https://identity.consignlyhq.com/connect/authorize?
  response_type=code&
  client_id=CLIENT_ID&
  redirect_uri=REDIRECT_URI&
  scope=SCOPES&
  state=RANDOM_STATE_VALUE

Step 2: Handle the Callback

After authorization, the user is redirected to the registered redirect_uri with an authorization code:

https://app.com/callback?code=AUTHORIZATION_CODE&state=STATE_VALUE

Step 3: Exchange Code for Token

curl -X POST https://identity.consignlyhq.com/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "client_id=CLIENT_ID" \
  -d "client_secret=CLIENT_SECRET" \
  -d "redirect_uri=REDIRECT_URI"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4..."
}

Using Access Tokens

The access token must be included in the Authorization header of all API requests:

curl -X GET https://api.consignlyhq.com/v1/identity \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Refreshing Tokens

When using the Authorization Code flow, a refresh token is received that can be used to obtain new access tokens without requiring user interaction:

curl -X POST https://identity.consignlyhq.com/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=REFRESH_TOKEN" \
  -d "client_id=CLIENT_ID" \
  -d "client_secret=CLIENT_SECRET"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "bmV3IHJlZnJlc2ggdG9rZW4..."
}

Token Expiration

Note: Authorization codes must be exchanged for tokens within 1 minute of being issued. Refresh tokens should be stored securely and used to obtain new access tokens before they expire.

OAuth Scopes

Scopes define the permissions the application has access to. Only the scopes necessary for the integration should be requested.

Scope Selection Tips:

• Use read scopes when only fetching data is required
• The consignment scope is required for import operations
• The financial scope is needed to access charges and schedules

Best Practices

Secure Storage

• Client secrets and tokens should be stored securely (e.g., environment variables, secret managers)
• Credentials must not be exposed in client-side code or version control
• HTTPS must be used for all API communications

Token Management

• Access tokens should be cached and reused until they expire
• Token refresh logic should be implemented to handle expiration gracefully
• 401 Unauthorized responses should be handled by refreshing the token and retrying

Rate Limiting

The API enforces rate limits to ensure fair usage. See Error Handling for details on rate limits and handling 429 responses.

Verifying the Connection

After obtaining an access token, the connection can be verified by calling the Identity endpoint:

curl -X GET https://api.consignlyhq.com/v1/identity \
  -H "Authorization: Bearer ACCESS_TOKEN"

A successful response confirms authentication is working:

{
  "identityConnectionId": "550e8400-e29b-41d4-a716-446655440000",
  "userId": "550e8400-e29b-41d4-a716-446655440001",
  "userFullName": "API User",
  "organisationId": "550e8400-e29b-41d4-a716-446655440002",
  "organisationName": "The Organisation",
  "partnerId": "550e8400-e29b-41d4-a716-446655440003",
  "partnerCode": "PART",
  "partnerName": "The Partner"
}

Troubleshooting

Additional Resources

• Create Custom Apps - Detailed guide on creating and configuring custom apps
• Error Handling - Complete error code reference