API Authentication

The YumKiosk public API is authenticated with Laravel Sanctum personal-access tokens. You exchange an email and password for a bearer token, then include that token on every subsequent request. Tokens are long-lived — they do not expire automatically — but you can revoke them any time from the agent dashboard or by calling the logout endpoint.

This page covers how to obtain a token, how to use it, and how the server resolves your token back to an owner so that every request is scoped correctly.

#Obtaining a token

Token issuance is a single unauthenticated POST against the auth endpoint. Pass the email and password of an agent user (not an owner email — owner accounts are panel-only).

curl -X POST https://admin.yumkiosk.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"agent@example.com","password":"secret"}'

The response contains the token and basic user details:

{
  "token": "12|abcd1234...longhex...",
  "user": {
    "id": 42,
    "name": "Alice",
    "email": "agent@example.com",
    "is_agent": true,
    "agent_status": "available"
  }
}

Store the token somewhere safe. It is shown exactly once — the server does not keep a plaintext copy.

#Making authenticated requests

Include the token as a bearer header on every request. Most HTTP clients have a built-in mechanism for this, but the raw form is:

Authorization: Bearer 12|abcd1234...longhex...
Accept: application/json

All public endpoints live under the /api/v1/* prefix. For example, to list recent orders:

curl https://admin.yumkiosk.com/api/v1/orders \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

#Owner scoping

The server looks at the agent attached to your token and resolves their owner_id. Every response is then filtered to only show data belonging to that owner — you cannot access orders, kiosks, or sessions from another owner even if you know the IDs. Attempts to load resources outside your owner return 404 Not Found.

If your token is associated with an agent that has no owner_id (for example, a sandbox or demo account), the server returns 403 Forbidden with the message Token not associated with an owner.

#Rate limits

Authenticated API calls are throttled by the api rate limiter: 120 requests per minute per user. Exceed this and you receive 429 Too Many Requests with a Retry-After header. The limit is keyed on the user ID, so multiple tokens for the same user share the bucket.

#Revoking tokens

Three ways to revoke:

1. Logout endpoint — POST /api/auth/logout with the token revokes that specific token only.
2. Agent dashboard — the agent can list their tokens under Settings → API Tokens and revoke individual ones.
3. Owner panel — the owner can disable an agent user, which cascades and invalidates every token attached to it.

Revoked tokens return 401 Unauthorized on the next request. There is no refresh step — issue a new token via /api/auth/login when that happens.

#Security notes

Do not commit tokens to source control. Do not send them over non-TLS connections (the server rejects plain HTTP on the admin domain). Do not share tokens across environments — issue one per deployment, per service, so you can revoke granularly if one gets leaked. When a token is leaked, revoke it immediately — stolen tokens have full read access to your owner's order history, menu, and kiosk fleet.