What you can build
- Read the trips, routes, stops, drivers and vehicles of every operator that connected your app (
*:readscopes). - Write trips: create, change, cancel and reschedule them, assign a driver and vehicle, rewrite their stops (
trips:write, approved by the operator’s admin). Trips cannot be deleted through the API. - Subscribe to trip events (
trip.created,trip.rescheduled,trip.cancelled,trip.started,trip.completed). Stracker calls your https endpoint with a signed request, retries failures and keeps a delivery log. See webhooks.
The basics
| Topic | Value |
|---|---|
| Base URL | https://api.stracker.vn |
| Version | /v1 in every path. The webhook payloads carry an apiVersion date. |
| Format | JSON. The token endpoints take form bodies (application/x-www-form-urlencoded). |
| Authentication | OAuth 2.0 bearer tokens: Authorization: Bearer <access_token>. See authentication. |
| Errors | RFC 7807 application/problem+json with a stable code; the token endpoints answer RFC 6749 errors. See errors. |
| Discovery | /.well-known/oauth-authorization-server and /.well-known/jwks.json on the base URL. |
Get access
- Send a connection request with the form on the Developers page: your company, what you want to build, the redirect addresses and the scopes you need.
- Confirm your email. We send a link to your work address; the request reaches the Stracker team only after you open it.
- We review it. The team may email you a question.
- Collect your credentials. Once approved you get a one-time link to your client ID. A 6-digit code arrives in a separate email. The client secret is shown once, so store it at once; if you lose it, ask us to issue a new one. If you prefer to authenticate with a key pair instead of a secret, you register a public key on that same page (see private_key_jwt).
Two kinds of app
| Tenant app | Partner app | |
|---|---|---|
| Who builds it | An operator, for its own account. | A software company, for many operators. |
| Where it is created | By the operator’s admin in Stracker, under API keys. | By Stracker, after the review above. |
| Which data it reaches | Its own tenant. | Only a tenant that installed it, and only the scopes that tenant’s admin accepted. |
| Machine access (no user) | client_credentials. | client_credentials with tenant=<install_id>; needs the tenant:connect scope. |
Installing a partner app in a tenant
An operator’s admin installs your app from an install link you send them. The link installs nothing by itself: the admin signs in, sees your app, the publisher and each scope in plain words, may untick scopes, and chooses Accept or Decline.
state is required; redirect_uri must equal one you registered.https://app.stracker.vn/oauth/install
?client_id=YOUR_CLIENT_ID
&scope=trips%3Aread%20tenant%3Aconnect
&redirect_uri=https%3A%2F%2Fexample.com%2Fstracker%2Finstalled
&state=RANDOM_VALUE_YOU_CHECK_ON_RETURN- On Accept the admin returns to your
redirect_uriwithinstall_id,stateandiss:https://example.com/stracker/installed?install_id=sti_...&state=...&iss=https%3A%2F%2Fapi.stracker.vn. Keepinstall_id: it is thetenantvalue of your machine-access token requests. - On Decline the redirect carries
error=access_denied. - An admin may grant fewer scopes than you asked for, never more than your app registered. You can send the link again to ask for more.
- A user who is not an admin sees "Ask your admin" and the request goes to the tenant’s admins.
Testing without touching production data
Your first call
- Request an access token with your client ID and secret.
- Call the API with the token. A
client_credentialstoken lasts 30 minutes by default and has no refresh token: request a new one when it expires.
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"
}curl -sS "https://api.stracker.vn/v1/trips?limit=5" \
-H "Authorization: Bearer $ACCESS_TOKEN"Where next: authentication for the other flows, the scope reference, the generated API reference, and webhooks.