Getting started

Authentication

The Partner API uses OAuth2 client credentials. You exchange your client_id and client_secret for a short-lived bearer token, then send that token on every API call.

Official SDKs

An official PHP SDK is available now — composer require starmile/partner-sdk (PHP 7.1+). It handles authentication, retries and typed errors for you. Every endpoint in this reference includes a PHP tab next to the cURL example. Node.js and Python SDKs are on the way.

Run it in Postman

Import the collection and one environment, set your client_id and client_secret, then run Authentication › Get access token — every other request inherits the bearer token automatically.

Download collection Production environment Sandbox environment

The two environments are identical in shape — set each environment’s base_url and credential to the values your partner gives you for that environment.

There is no user login in this flow — the credential itself is your identity. Keep the client_secret server-side; never expose it in a browser or mobile app. If a secret is leaked, ask your partner to rotate it (the old secret stops working immediately).

Using the token

Send the access token as a bearer token on every request: Authorization: Bearer <access_token>. Tokens are short-lived (typically one hour); when one expires, request a new one with the same credential.

Obtain an access token

POST/oauth/token

Exchange your client credentials for a bearer token for machine-to-machine access. Send the body as JSON or asapplication/x-www-form-urlencoded.

Request body

grant_typestringrequired: Must be "client_credentials".
client_idstringrequired: The client identifier issued to you.
client_secretstringrequired: The client secret issued to you.

Response (200)

token_typestringoptional: Always "Bearer".
expires_inintegeroptional: Seconds until the access token expires.
access_tokenstringoptional: The bearer token to send on subsequent requests.

curl -X POST https://api.starmile.io/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "client_secret": "<your client secret>"
  }'