Skip to content

ApiToken

Jump to bottom
Viames Marino edited this page May 10, 2026 · 1 revision

Pair framework: ApiToken

Pair\Models\ApiToken stores mobile/API bearer sessions with short-lived access tokens and optional rotating refresh tokens.

It is the Pair v4 backend companion for native mobile clients such as PairMobileKit and PairMobileAndroid. It is separate from browser cookies, PHP sessions, remember-me records, and the legacy OAuth2Token client-credentials flow.

When to use

Use ApiToken when a native app or API client should authenticate with a Bearer access token and keep a persistent refresh token for background session renewal.

Pair's API runtime checks api_tokens before falling back to legacy OAuth2Token validation. If the migration is not installed yet, Pair keeps the legacy bearer path working instead of rejecting all API traffic.

Storage

Apply the migration before enabling the default mobile auth endpoints:

migrations/20260510_api_tokens.sql
migrations/20260510_api_tokens_device_metadata.sql

The api_tokens table stores:

  • user ID
  • SHA-256 access-token hash
  • optional SHA-256 refresh-token hash
  • access and refresh expiration timestamps
  • optional device hash and password-version hash for application-owned invalidation policy
  • optional device name, IP address, and user agent
  • last_used_at, revoked_at, created_at, and updated_at

Raw token values are returned only when issued or refreshed. They are never stored in plain text.

Configuration

Token lifetimes are read from Env:

PAIR_MOBILE_ACCESS_TOKEN_LIFETIME=900
PAIR_MOBILE_REFRESH_TOKEN_LIFETIME=2592000

Invalid or non-positive values fall back to the defaults above.

Main methods

issueForUser(User $user, bool $withRefreshToken = true, ?string $deviceName = null, ?string $ipAddress = null, ?string $userAgent = null, ?string $deviceHash = null, ?string $passwordVersionHash = null): array

Creates a bearer session row and returns the raw token values:

$issued = ApiToken::issueForUser(
	$user,
	true,
	'iPhone 15',
	$_SERVER['REMOTE_ADDR'] ?? null,
	$_SERVER['HTTP_USER_AGENT'] ?? null,
	$deviceHash,
	$passwordVersionHash
);

The returned array contains:

  • token: the ApiToken record
  • accessToken: the raw access token
  • refreshToken: the raw refresh token or null

getActiveByAccessToken(string $accessToken): ?ApiToken

Loads the active token row for a Bearer access token. The token must exist, must not be expired, and must not be revoked.

The API runtime uses this method during bearer bootstrap. If the related user is disabled or locked by faults, Pair revokes the token and rejects the request.

refresh(string $refreshToken): ?array

Rotates a refresh token and returns a fresh bearer session payload.

The old refresh-token hash is included in the UPDATE condition, so concurrent refresh calls are coalesced safely at the database level: one request rotates the token, and later requests using the old value fail.

revokeByRefreshToken(string $refreshToken): bool

Revokes the active row matching a refresh token. The built-in mobile logout endpoint calls this when the app includes refresh_token in the JSON body.

revokeByIdForUser(int $tokenId, User $user): bool

Revokes one active token row only when it belongs to the supplied user. Application admin endpoints should use this method for device-level mobile logout after their own permission and tenant checks pass.

revokeAllForUser(User $user): int

Revokes every active mobile token row for the supplied user and returns the number of affected rows. Application admin endpoints should use this method for account-wide mobile logout.

revokeAllForUserAndDevice(User $user, string $deviceHash): int

Revokes every active mobile token row for one user and one device hash. Applications can use this for per-device logout when they issue bearer tokens with a stable, non-secret device hash.

revoke(): bool

Revokes the current token row.

getUser(): ?User

Loads the user associated with the token.

accessExpiresAtIso(): string

Returns the access-token expiration in ISO 8601 format for API responses.

Built-in API flow

ApiController::authAction() uses ApiToken for:

  • POST /api/auth/login
  • POST /api/auth/register
  • POST /api/auth/refresh
  • GET /api/auth/me
  • POST /api/auth/logout or DELETE /api/auth/logout

Applications can override mobileAuthUserSnapshot(), mobileAuthContext(), and mobileAuthRegisterUser() in their API controller to adapt the standard payload without rewriting token storage.

Administrative revocation

Pair does not expose generic admin token-revocation endpoints in the core API because admin ACL, tenant scope, support impersonation, and audit rules are application-specific.

Recommended application endpoints:

  • GET /api/admin/users/{userId}/tokens
  • DELETE /api/admin/users/{userId}/tokens/{tokenId}
  • DELETE /api/admin/users/{userId}/tokens

Never return raw token hashes. Show safe metadata only, scope every lookup to the permitted account or tenant, and write an audit record when support or admin users revoke another user's tokens.

See also: Mobile auth app setup, Mobile iOS stack, Mobile Android stack, ApiController, User, OAuth2Token, Configuration file.

Clone this wiki locally