Authentication

Obi FARE.AI uses a two-step credential model: a long-lived API key + secret pair that lives in your server's secret store, exchanged on demand for a short-lived JWT used on every other call.

Issuing a token

POST /v1/auth/token takes two headers — never put the secret in the request body or query string.

curl -XPOST https://api.obifareai.com/v1/auth/token \
  -H "X-API-KEY: pgw_..." \
  -H "X-API-SECRET: <your-secret>"

Response (200 OK):

{
  "token":      "eyJ0eXAiOiJKV1Q...",
  "jti":        "48e86a73-9e90-4c50-a634-a6f7ab47e583",
  "expiresAt":  "2026-05-19T16:03:39.701484Z",
  "ttlSeconds": 86400
}

TTL semantics: default 24h (86400s). Operators can shorten or extend per account, up to a maximum of 366 days.

Token shape: standard HS256-signed JWT. The jti is a stable identifier you can pass back to /v1/auth/revoke to invalidate a specific token before its natural expiry — or revoke every token your account holds with {"all": true}. expiresAt follows ISO-8601 with fractional seconds.

Calling authenticated endpoints

Pass the JWT as a bearer token:

curl https://api.obifareai.com/v1/customer/me \
  -H "Authorization: Bearer eyJ..."

Revoking a token

POST /v1/auth/revoke immediately invalidates the supplied jti. Effect is instant on the gateway instance that processed the revoke, and propagates to other instances within ~60 seconds. Pass {"all": true} instead of a jti to revoke every token your account currently holds — useful as a "panic button" if a secret leaks.

curl -XPOST https://api.obifareai.com/v1/auth/revoke \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"jti": "48e86a73-9e90-4c50-a634-a6f7ab47e583"}'

Account status

Customers come in three states: Active, Pending, and Blocked. Only Active accounts can issue tokens or call /v1/quote; Pending and Blocked accounts both receive 403 result:account-blocked. Existing tokens issued while Active are honored until their natural TTL OR until a snapshot-cache refresh propagates the status change — usually within 60 seconds. If you need an instant block, pair the status change with a revoke call.