Choose a flow
| Flow | Use it when | Access token | Refresh token |
|---|---|---|---|
client_credentials | Your server acts for itself, for one tenant: synchronisation, back office jobs, webhooks. | 30 minutes (1800 s) | None. Request a new token. |
authorization_code + PKCE | Your app acts for a signed-in user who consents: a partner portal, a mobile app. | 10 minutes (600 s) | With offline_access: 30 days idle, 365 days at most, rotated on every use. |
The lifetimes are the service defaults; read expires_in in each response instead of hard-coding them. Treat access tokens as opaque strings.
How your app proves who it is
| Method | How | For |
|---|---|---|
client_secret_basic | Authorization: Basic base64(client_id:client_secret) | Confidential apps with a secret. |
private_key_jwt | client_assertion_type and client_assertion: a short JWT you sign with your private key. Details below. | Confidential apps that prefer a key pair to a shared secret. |
none | Send client_id only; PKCE protects the code exchange. | Public apps (for example a native mobile app). |
Use one method per request. An app has one method at a time; sending Basic and an assertion together is an invalid_request.
client_credentials
The scopes are optional and must be inside the set your app was approved for. Ask only for what you need.
curl -sS https://api.stracker.vn/v1/oauth/token \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-d grant_type=client_credentials \
-d scope="trips:read routes:read"{
"access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K2p3dCIsImtpZCI6Ii4uLiJ9...",
"token_type": "Bearer",
"expires_in": 1800,
"scope": "trips:read routes:read"
}Partner apps: name the tenant
A partner app serves many tenants, so a client_credentials request names the tenant with tenant=<install_id> (the sti_... value from the install). It works only for an active install of your own app whose scopes include tenant:connect.
curl -sS https://api.stracker.vn/v1/oauth/token \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-d grant_type=client_credentials \
-d tenant="$INSTALL_ID" \
-d scope="trips:read"authorization_code with PKCE
The user approves your app on a Stracker page, you receive a one-time code on your redirect address and exchange it for tokens. PKCE with S256 is required for every app, confidential or public; plain is refused.
- Make a verifier and a challenge. The verifier is a random string of 43 to 128 URL-safe characters; the challenge is the base64url of its SHA-256.
- Send the user to the authorize page with the parameters below.
- The user signs in and approves. Stracker redirects to your
redirect_uriwithcode,stateandiss. Check thatstateis the one you sent and thatissishttps://api.stracker.vn. - Exchange the code within 60 seconds. A code works once; presenting it again revokes the grant it produced.
- Call the API with the access token.
# 1. A random code_verifier (43-128 characters of A-Z a-z 0-9 - . _ ~)
CODE_VERIFIER=$(openssl rand -base64 48 | tr '+/' '-_' | tr -d '=\n')
# 2. Its S256 challenge: BASE64URL(SHA256(code_verifier))
CODE_CHALLENGE=$(printf %s "$CODE_VERIFIER" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')https://app.stracker.vn/oauth/authorize
?response_type=code
&client_id=YOUR_CLIENT_ID
&redirect_uri=https%3A%2F%2Fexample.com%2Fstracker%2Fcallback
&scope=trips%3Aread%20offline_access
&state=RANDOM_VALUE_YOU_CHECK_ON_RETURN
&code_challenge=CODE_CHALLENGE
&code_challenge_method=S256| Parameter | Value |
|---|---|
response_type | code |
client_id | Your client ID. |
redirect_uri | Exactly one of the addresses you registered (exact string match). https only; native public apps may use http://127.0.0.1:<port> or a private-use scheme. |
scope | Space-separated scopes. Add offline_access to receive a refresh token. |
state | A random value you check on return. |
code_challenge, code_challenge_method | The S256 challenge and the literal S256. |
https://example.com/stracker/callback?code=stco_...&state=RANDOM_VALUE_YOU_CHECK_ON_RETURN&iss=https%3A%2F%2Fapi.stracker.vn# Confidential client (has a secret): authenticate with Basic
curl -sS https://api.stracker.vn/v1/oauth/token \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-d grant_type=authorization_code \
-d code="$CODE" \
-d redirect_uri="https://example.com/stracker/callback" \
-d code_verifier="$CODE_VERIFIER"
# Public client (no secret, for example a native app): send client_id instead
curl -sS https://api.stracker.vn/v1/oauth/token \
-d grant_type=authorization_code \
-d client_id="$CLIENT_ID" \
-d code="$CODE" \
-d redirect_uri="myapp://stracker/callback" \
-d code_verifier="$CODE_VERIFIER"{
"access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K2p3dCIsImtpZCI6Ii4uLiJ9...",
"token_type": "Bearer",
"expires_in": 600,
"scope": "trips:read offline_access",
"refresh_token": "stcr_..."
}Refresh tokens
Ask for offline_access to get a refresh token (stcr_...). Every use rotates it: the response carries a new refresh token and the old one is spent. A refresh can narrow the scopes, never widen them.
curl -sS https://api.stracker.vn/v1/oauth/token \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-d grant_type=refresh_token \
-d refresh_token="$REFRESH_TOKEN"private_key_jwt: sign instead of sharing a secret
Instead of a client secret, your app registers a public key and proves itself with a short-lived JWT signed by the private key (RFC 7523, OpenID Connect private_key_jwt). No secret travels, and you can rotate keys without a shared value to coordinate. It works for client_credentials, authorization_code, refresh_token, revoke and introspect.
1. Generate a key pair
ES256 (an EC key on P-256) is recommended. RS256 needs an RSA key of 2048 to 8192 bits with public exponent 65537. The private key stays on your side and never leaves it.
# ES256: an EC key on the P-256 curve, private key in PKCS#8
openssl ecparam -name prime256v1 -genkey -noout | openssl pkcs8 -topk8 -nocrypt -out private.pem
openssl pkey -in private.pem -pubout -out public.pem# RS256: RSA 2048 to 8192 bits (public exponent 65537)
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out private.pem
openssl pkey -in private.pem -pubout -out public.pemconst { generateKeyPairSync } = require('node:crypto');
const fs = require('node:fs');
const kid = process.argv[2] ?? 'my-key-1'; // 1-64 characters of A-Z a-z 0-9 . _ -
const { privateKey, publicKey } = generateKeyPairSync('ec', { namedCurve: 'P-256' });
// The private key never leaves your machine; keep it out of version control.
fs.writeFileSync('private.pem', privateKey.export({ type: 'pkcs8', format: 'pem' }), { mode: 0o600 });
// Paste this public JWK into Stracker (API keys > OAuth apps > Keys).
const jwk = { ...publicKey.export({ format: 'jwk' }), kid, alg: 'ES256', use: 'sig' };
console.log(JSON.stringify(jwk, null, 2));2. Register the public key
You register the public key as a JWK (RFC 7517). The Node.js script above prints one; to convert public.pem use:
// Turn public.pem into the public JWK Stracker asks for
const { createPublicKey } = require('node:crypto');
const fs = require('node:fs');
const jwk = createPublicKey(fs.readFileSync('public.pem')).export({ format: 'jwk' });
console.log(JSON.stringify({ ...jwk, kid: 'my-key-1', use: 'sig' }, null, 2));{
"kty": "EC",
"crv": "P-256",
"x": "...base64url...",
"y": "...base64url...",
"kid": "my-key-1",
"alg": "ES256",
"use": "sig"
}- Accepted:
ECwith curveP-256, orRSAof 2048 to 8192 bits with exponent 65537. kidis required: 1 to 64 characters fromA-Z a-z 0-9 . _ -. It must be unique among the app’s live keys.- Refused: any private member (
d,p,q,dp,dq,qi,oth,k), auseother thansig, analgthat does not match the key type, a point that is not on the curve. Other members are dropped. - An app holds at most 5 live keys. Add the new key before you revoke the old one; the last live key of an app that uses keys cannot be revoked.
- Tenant apps: the operator’s admin registers the key on the app in Stracker, under API keys. Partner apps: the credential hand-off link we send you (the same one that would reveal a secret) lets you register your key instead.
3. Build and sign the assertion
// Header
{ "alg": "ES256", "typ": "JWT", "kid": "my-key-1" }
// Claims
{
"iss": "YOUR_CLIENT_ID",
"sub": "YOUR_CLIENT_ID",
"aud": "https://api.stracker.vn/v1/oauth/token",
"iat": 1763104324,
"exp": 1763104384,
"jti": "f3c1b7a2-3d52-4b5a-9d6c-0f6a53b0a111"
}| Part | Rule |
|---|---|
alg | ES256 or RS256 only. none, HS*, and headers such as jku, x5u, jwk, x5c or crit are refused: keys come only from the set you registered. |
kid | The kid of the key you signed with. Recommended; it saves the server trying every key. |
iss and sub | Both equal your client ID. |
aud | Exactly one value: the token endpoint URL https://api.stracker.vn/v1/oauth/token (also accepted: the issuer, https://api.stracker.vn). A list of audiences is refused. |
exp | Required, at most 5 minutes ahead. iat and nbf are optional and checked when present; exp - iat is at most 5 minutes. A clock skew of 30 seconds is tolerated. |
jti | Required, unique. An assertion works once: the jti is remembered until exp, and a replay is refused. Make a new one for every request. |
| Size | At most 8192 characters. client_id, if you send it, must equal iss. |
The ES256 signature is the raw 64-byte r || s form that JWS uses, not the DER form some libraries produce by default. The samples show how to get it right.
const crypto = require('node:crypto');
const fs = require('node:fs');
const CLIENT_ID = process.env.STRACKER_CLIENT_ID;
const KID = 'my-key-1'; // the kid you registered with the public key
const TOKEN_URL = 'https://api.stracker.vn/v1/oauth/token';
const b64u = (value) => Buffer.from(value).toString('base64url');
function clientAssertion(privateKeyPem) {
const now = Math.floor(Date.now() / 1000);
const header = { alg: 'ES256', typ: 'JWT', kid: KID };
const claims = {
iss: CLIENT_ID,
sub: CLIENT_ID,
aud: TOKEN_URL, // exactly one audience
iat: now,
exp: now + 60, // at most 5 minutes ahead
jti: crypto.randomUUID(), // single use: a new one for every request
};
const input = `${b64u(JSON.stringify(header))}.${b64u(JSON.stringify(claims))}`;
// JWS wants r||s (IEEE P1363), not the DER form Node signs with by default.
const signature = crypto.sign('sha256', Buffer.from(input), { key: privateKeyPem, dsaEncoding: 'ieee-p1363' });
return `${input}.${signature.toString('base64url')}`;
}
async function getToken() {
const body = new URLSearchParams({
grant_type: 'client_credentials',
scope: 'trips:read',
client_assertion_type: 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
client_assertion: clientAssertion(fs.readFileSync('private.pem', 'utf8')),
});
const response = await fetch(TOKEN_URL, { method: 'POST', body });
return response.json(); // { access_token, token_type: 'Bearer', expires_in, scope }
}import os
import time
import uuid
import jwt # PyJWT, with the "cryptography" extra: pip install "pyjwt[crypto]" requests
import requests
CLIENT_ID = os.environ["STRACKER_CLIENT_ID"]
KID = "my-key-1" # the kid you registered with the public key
TOKEN_URL = "https://api.stracker.vn/v1/oauth/token"
def client_assertion(private_key_pem: str) -> str:
now = int(time.time())
claims = {
"iss": CLIENT_ID,
"sub": CLIENT_ID,
"aud": TOKEN_URL, # exactly one audience
"iat": now,
"exp": now + 60, # at most 5 minutes ahead
"jti": str(uuid.uuid4()), # single use: a new one for every request
}
return jwt.encode(claims, private_key_pem, algorithm="ES256", headers={"kid": KID})
def get_token() -> dict:
with open("private.pem") as handle:
assertion = client_assertion(handle.read())
response = requests.post(
TOKEN_URL,
data={
"grant_type": "client_credentials",
"scope": "trips:read",
"client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
"client_assertion": assertion,
},
timeout=10,
)
return response.json() # {"access_token": ..., "token_type": "Bearer", "expires_in": ..., "scope": ...}4. Request the token
curl -sS https://api.stracker.vn/v1/oauth/token \
-d grant_type=client_credentials \
-d scope="trips:read" \
-d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
-d client_assertion="$CLIENT_ASSERTION"- Every failure of the assertion (bad signature, wrong
aud, expired, replayed, unknown or expired key) is the same401 invalid_client, so a probe learns nothing. When it fails, check your clock, theaud, thekidand that the key is registered and live. - Sending Basic and an assertion together, a wrong
client_assertion_type, a repeated parameter, or aclient_idthat differs fromissis a400 invalid_request. - Switching an app from a secret to keys: the existing secrets keep working for 24 hours, then stop. An app that has no unexpired secret refuses Basic.
Revoke and introspect
Revoke (RFC 7009) answers 200 {} once your app authenticates, whether or not the token was live. Revoking a refresh token ends the whole grant; revoking an access token ends only that token. Introspect (RFC 7662) is for confidential apps and answers { "active": false } for every token that is not live for you.
# Revoke an access token or a refresh token (a refresh token ends the whole grant). Always answers 200 {}.
curl -sS https://api.stracker.vn/v1/oauth/revoke \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-d token="$TOKEN"
# Ask whether a token is live (confidential clients only)
curl -sS https://api.stracker.vn/v1/oauth/introspect \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-d token="$TOKEN"Discovery
| What | URL |
|---|---|
| Authorization server metadata (RFC 8414) | https://api.stracker.vn/.well-known/oauth-authorization-server |
| Signing keys (JWKS) | https://api.stracker.vn/.well-known/jwks.json |
| Authorize page | https://app.stracker.vn/oauth/authorize |
| Token, revoke, introspect | https://api.stracker.vn/v1/oauth/token, /v1/oauth/revoke, /v1/oauth/introspect |
curl -sS https://api.stracker.vn/.well-known/oauth-authorization-server
curl -sS https://api.stracker.vn/.well-known/jwks.jsonCalling the API
- Send
Authorization: Bearer <access_token>. Tokens never go in a URL. - A route is closed to OAuth tokens unless it is in the API reference:
403 OAUTH_ROUTE_NOT_EXPOSED. - Each request is checked again: a disabled app, a revoked grant, a suspended tenant or a removed
apiextension stops the token within about 30 seconds. See errors for the codes. - A token for the wrong scope answers
403 OAUTH_INSUFFICIENT_SCOPEwithWWW-Authenticate: Bearer error="insufficient_scope"and the scope it needs.