Docs

Authentication

The API accepts OAuth 2.0 access tokens only. Pick the flow by who is acting: your server on its own, or a signed-in user who approved your app.

Choose a flow

FlowUse it whenAccess tokenRefresh token
client_credentialsYour server acts for itself, for one tenant: synchronisation, back office jobs, webhooks.30 minutes (1800 s)None. Request a new token.
authorization_code + PKCEYour 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

MethodHowFor
client_secret_basicAuthorization: Basic base64(client_id:client_secret)Confidential apps with a secret.
private_key_jwtclient_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.
noneSend 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
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"
JSON
{
  "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
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.

  1. 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.
  2. Send the user to the authorize page with the parameters below.
  3. The user signs in and approves. Stracker redirects to your redirect_uri with code, state and iss. Check that state is the one you sent and that iss is https://api.stracker.vn.
  4. Exchange the code within 60 seconds. A code works once; presenting it again revokes the grant it produced.
  5. Call the API with the access token.
Shell
# 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 '=')
URL
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
ParameterValue
response_typecode
client_idYour client ID.
redirect_uriExactly 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.
scopeSpace-separated scopes. Add offline_access to receive a refresh token.
stateA random value you check on return.
code_challenge, code_challenge_methodThe S256 challenge and the literal S256.
URLWhat your redirect address receives.
https://example.com/stracker/callback?code=stco_...&state=RANDOM_VALUE_YOU_CHECK_ON_RETURN&iss=https%3A%2F%2Fapi.stracker.vn
curl
# 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"
JSON
{
  "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
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.

OpenSSL (ES256)
# 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
OpenSSL (RS256)
# 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.pem
Node.js
const { 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:

Node.js
// 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));
JSON
{
  "kty": "EC",
  "crv": "P-256",
  "x": "...base64url...",
  "y": "...base64url...",
  "kid": "my-key-1",
  "alg": "ES256",
  "use": "sig"
}
  • Accepted: EC with curve P-256, or RSA of 2048 to 8192 bits with exponent 65537.
  • kid is required: 1 to 64 characters from A-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), a use other than sig, an alg that 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

JSON
// 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"
}
PartRule
algES256 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.
kidThe kid of the key you signed with. Recommended; it saves the server trying every key.
iss and subBoth equal your client ID.
audExactly 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.
expRequired, 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.
jtiRequired, unique. An assertion works once: the jti is remembered until exp, and a replay is refused. Make a new one for every request.
SizeAt 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.

Node.js
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 }
}
Python
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
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 same 401 invalid_client, so a probe learns nothing. When it fails, check your clock, the aud, the kid and that the key is registered and live.
  • Sending Basic and an assertion together, a wrong client_assertion_type, a repeated parameter, or a client_id that differs from iss is a 400 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.

curl
# 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

WhatURL
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 pagehttps://app.stracker.vn/oauth/authorize
Token, revoke, introspecthttps://api.stracker.vn/v1/oauth/token, /v1/oauth/revoke, /v1/oauth/introspect
curl
curl -sS https://api.stracker.vn/.well-known/oauth-authorization-server
curl -sS https://api.stracker.vn/.well-known/jwks.json

Calling 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 api extension stops the token within about 30 seconds. See errors for the codes.
  • A token for the wrong scope answers 403 OAUTH_INSUFFICIENT_SCOPE with WWW-Authenticate: Bearer error="insufficient_scope" and the scope it needs.