API Keys

Personal access tokens that let external systems act as a user against the mobility API.

API Keys

An API key in Yipii Mobility is a personal access token scoped to your user account and your current tenant. External systems — a warehouse MES, a custom dashboard, an integration script — use a key to authenticate against /api/{tenant}/... endpoints and act as you, subject to the same role and permission checks you have in the UI.

How they compare to session auth

Creating a key

1. Developer Settings → API Keys from the sidebar (the Developer section is visible when you have at least the admin role).

2. Create key.

3. Name — a human label, e.g. Warehouse PO sync. Shown in the list and in the audit log.

4. Abilities — optional list of scopes. Leave empty for "full access, whatever the user can do." Commonly used scopes:

   • read:assets
   • write:work-orders
   • read:fuel-logs
   • write:odometer-entries

   The backend enforces scopes via $request->user()->tokenCan('ability') — any endpoint that matters calls this. If you forget to declare a scope the endpoint needs, requests with the token will 403.

5. Expiry — optional. Leave blank for "never expires." Set a concrete date for contractor access or one-off imports.

6. Save.

The plaintext token is shown exactly once on the next screen. It's not stored — the database only keeps a hashed copy. Copy it, paste it into your consuming system, and dismiss the dialog. If you lose it, revoke and create a new one.

Using a key

Every request needs the token in the Authorization header:

curl https://mobility-api.yipii.io/api/acme/assets \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Accept: application/json"

Keys are tenant-bound: the token is issued against the tenant you were inside when you created it. A token for the acme tenant cannot be used against globex — the URL prefix must match.

Revoking

From Developer Settings → API Keys, click Revoke on any row. The row is soft-deleted and the hashed token is immediately rejected by the auth guard. Requests using a revoked token get 401 Unauthorised.

Revoked keys stay in the table for 90 days (with a deleted_at timestamp) so the audit log still resolves the attribution for historical calls, then are hard-deleted by a scheduled job.

Rotation

Best practice for long-lived integrations:

1. Create a new key with the same scopes.
2. Update the consuming system to use the new token.
3. Once you've confirmed the consumer is on the new key, revoke the old one.

There's no automated rotation in the UI today. If you need compliance-driven rotation (90-day cycles, etc.), wire a cron that does the above via the API — every endpoint used in the flow is itself callable with a token.

API surface

These endpoints are themselves callable with an API key, which means you can provision and rotate tokens programmatically.

Audit

Every API call carries the token's owner as causer_id, so actions taken via an integration are fully attributable in the Audit Log. The audit log also records token creations and revocations.

Permissions

• Any user — can create, list, and revoke their own keys.
• Admin — can see and revoke other users' keys via the Nova admin.
• The "Developer" sidebar section is gated on role admin to keep the UI simple.

Related

• Audit Log — trace every API call back to the key owner.
• Roles & Permissions — the scopes you can grant to a key are a subset of your own permissions.
• Webhooks (planned) — the inverse direction: we call you instead of you calling us.