> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wellapp.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# TempAccessToken

> TempAccessToken is a short-lived, single-use JWT backing record used to authenticate guest OAuth connector install flows

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       | — <sub>(not a records root)</sub> |
| REST base                       | `/v1/temp-access-tokens`          |
| Entity class                    | `TempAccessToken`                 |

<Note>
  **Internal object.** Not currently exposed on the public REST API. The operations below describe the intended contract.
</Note>

## 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 &gt; 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

```json theme={null}
{
  "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"
    }
  }
}
```

<sub>Source: `apps/api/src/database/entities/TempAccessToken.ts` · domain: platform · tier: Platform</sub>