TempAccessToken

TempAccessToken is a short-lived, single-use JWT backing record used to authenticate guest OAuth connector install flows. It is created by TempTokenService.generateTempToken() when the API issues a signed 15-minute connector-access URL and is consumed (marked used) by TempTokenService.validateAndConsume() during the OAuth callback. The table acts as a replay-prevention store: a token is valid only while expires_at > now() and used_at IS NULL. It has no workspace foreign key, no soft-delete column, and no user-editable fields — it is entirely system-managed.

Naming	Value
Object	TempAccessToken
Resource type (JSON:API `type`)	`temp_access_token`
Collection / records root	— _{(not a records root)}
REST base	`/v1/temp-access-tokens`
Entity class	`TempAccessToken`

Internal object. Not currently exposed on the public REST API. The operations below describe the intended contract.

API operations

Operation	Method & path	Status
List	`GET /v1/temp-access-tokens`	🟡 Planned
Retrieve	`GET /v1/temp-access-tokens/{id}`	🟡 Planned
Create	`POST /v1/temp-access-tokens`	🟡 Planned
Update	`PATCH /v1/temp-access-tokens/{id}`	🟡 Planned
Delete	`DELETE /v1/temp-access-tokens/{id}`	🟡 Planned

Data model

Attributes

Field	Type	Required	Constraints	Allowed values	Description
jti	uuid (PK) 🔒 system	✅ Yes	PRIMARY KEY; set by service via crypto.randomUUID() — not a database-generated default	Any valid UUID v4	JWT ID. Serves as both the database primary key and the `jti` claim embedded in the signed JWT. Used to look up and validate the token during verify and consume operations.
temp_access_token_id	uuid 🔒 system	✅ Yes	DEFAULT gen_random_uuid(); NOT NULL; added in Migration20260128100000	Any valid UUID v4	Public-facing stable identifier for the token record. Returned to callers as the resource `id` in API responses. Generated at row-insert time by the database.
expires_at	timestamptz 🔒 system	✅ Yes	NOT NULL; set to now() + 15 minutes at creation by TempTokenService	Future timestamp at creation; past timestamp marks expiry	Absolute expiry timestamp. The repository's findValidByJti query filters `expires_at > now()`. Tokens past this timestamp are treated as invalid regardless of `used_at`.
used_at	timestamptz 🔒 system	⚪ No	NULLABLE; set once by TempAccessTokenRepository.markAsUsed() on first successful consumption	null (unused) or a single timestamptz value (consumed)	Consumption timestamp. NULL means the token has not yet been used. Once set, findValidByJti will no longer return this row, enforcing single-use semantics.
created_at	timestamptz 🔒 system	✅ Yes	NOT NULL; set by @Property({ onCreate: () => new Date() }) in entity class	Timestamp at row creation	Creation timestamp, set by the MikroORM onCreate hook when the entity is first persisted. There is no updated_at column on this entity.

System-computed

temp_access_token_id — generated by the database via DEFAULT gen_random_uuid() at INSERT time (Migration20260128100000).
jti — set by the service layer using crypto.randomUUID() before persist; also embedded as the jti claim in the HS256-signed JWT returned to callers.
expires_at — computed by TempTokenService as Date.now() + 15 minutes (TOKEN_EXPIRY = 15 * 60 * 1000 ms) at generation time.
created_at — set by MikroORM onCreate hook (no database DEFAULT; application-side timestamp).
used_at — stamped by TempAccessTokenRepository.markAsUsed() exactly once upon successful validateAndConsume(). Never reset or cleared.
Single-use enforcement — findValidByJti combines three predicates: jti match + expires_at > now() + used_at IS NULL. All three must hold for the token to be considered valid.

Example

{
  "data": {
    "type": "temp_access_token",
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "attributes": {
      "temp_access_token_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "expires_at": "2026-06-02T15:45:00.000Z",
      "used_at": null,
      "created_at": "2026-06-02T15:30:00.000Z"
    }
  }
}

_{Source: apps/api/src/database/entities/TempAccessToken.ts · domain: platform · tier: Platform}