---
title: "Update a personal access token"
method: PATCH
path: "/pat/{id}"
tags: ["Personal access tokens"]
---

# Update a personal access token

`PATCH /pat/{id}`

## Request

- Base URL: `https://api.nullplatform.com`
- URL: `https://api.nullplatform.com/pat/{id}`
- Auth: HTTP bearer

Updates one of your personal access tokens. Send only what you want to change.

- The expiration can only move later, up to a year from now. An expired token can't be extended. Send it as `expires_in` or `expires_at`, not both.
- `grants` replaces all of the token's grants.
- Switching to `same_as_user` drops the token's grants. Switching back to `grants` requires the grants it should have.

## Path parameters

- `id` integer, required

## Request body

- PatWrite
  - `name` string: A descriptive name for the token.
  - `expires_in` integer: A later expiration, in seconds (at least 60), counted from the server's clock when it receives the request. Send this or `expires_at`, not both. The same rules as `expires_at` apply to the date it resolves to. Only `expires_at` is stored and returned.
  - `expires_at` string, date-time: A later expiration, at most a year from now. The expiration can't move earlier, and an expired token can't be extended. Send this or `expires_in`, not both.
  - `access` 'grants' | 'same_as_user': Leave it out to keep the token's current access. `same_as_user` drops the token's grants; switching back to `grants` requires `grants`.
  - `grants` union[]: The token's new grants. They replace all of its current ones.
    - union
      - object
        - `nrn` string, required: The NRN of the resource where the API key's role is assigned.
        - `role_slug` string, required: The slug of the role assigned to the API key for this NRN. > Note: See [Roles](/docs/authorization/roles) for more info. >
      - object
        - `nrn` string, required: The NRN of the resource where the API key's role is assigned.
        - `role_id` integer, required: The ID of the role assigned to the API key for this NRN. > Note: See [Roles](/docs/authorization/roles) for more info. >
      - object
        - `nrn` string, required: The NRN of the resource the grant applies to.
        - `actions` string[], required: The actions the API key may call at this NRN, without naming an existing role. nullplatform creates a role private to the key carrying exactly these actions. > Note: You can only grant actions you could hand out at that NRN yourself: the ones > you hold there, plus the ones carried by roles you may assign to an API key there. >
      - object
        - `nrn` string, required: The NRN of the resource the grant applies to.
        - `inherits` union[], required: Existing roles, by slug or ID, merged into a single role private to this key. Inheriting two roles in one grant is not the same as granting them separately: it produces one role, which `actions.add` and `actions.remove` can then adjust. You must be allowed to assign each inherited role to an API key at this NRN, the same check a grant by `role_id` passes. The key follows the roles it inherits: an action later added to one of them reaches the key too. > Note: A role private to another API key cannot be inherited. >
          - union
            - string
            - integer
        - `actions` object: How the union of the inherited roles is adjusted.
          - `add` string[]: Actions granted on top of what the inherited roles provide. Measured against what you can hand out at this NRN.
          - `remove` string[]: Inherited actions excluded from this grant. Each must be carried by one of the inherited roles, and none may also be in `add`.
  - `tags` object[]: The token's new tags. They replace all of its current ones.
    - `key` string: Tag key.
    - `value` string: Tag value.

## Response `200`

The operation was successful.

- PatResponse
  - `id` integer, required: Unique ID for the token.
  - `name` string, required: The descriptive name given to the token.
  - `masked_api_key` string: The token, masked.
  - `access` 'grants' | 'same_as_user', required: Whether the token follows your access (`same_as_user`) or holds its own grants (`grants`).
  - `tags` object[], required: Tags associated with the token. Empty when it has none.
    - `key` string, required: Tag key.
    - `value` string, required: Tag value.
  - `grants` object[], required: What the token can do. For a `same_as_user` token, these are your own grants in the organization at the moment of the request. A token that no longer works, because it expired or your user is inactive, reports none.
    - `id` integer: The ID of the grant.
    - `nrn` string: The NRN of the resource the grant applies to.
    - `role_id` integer: The ID of the role granted.
    - `role_slug` string: The slug of the role granted.
    - `actions` string[]: The action names the grant resolves to, present when it was created from `actions` or `inherits`.
  - `personal` boolean: Always `true` for a personal access token.
  - `owner_id` integer: The ID of the user who created the token.
  - `acting_user_id` integer: The ID of the user the token acts as: you.
  - `last_used_at` string, date-time, nullable: The ISO-8601 UTC timestamp of when the token was last exchanged for an access token.
  - `expires_at` string, date-time, required: The ISO-8601 UTC timestamp of when the token stops working.
  - `expired` boolean: Whether the token has expired.
  - `created_at` string, date-time, required: The ISO-8601 UTC timestamp of when the token was created.
  - `updated_at` string, date-time, required: The ISO-8601 UTC timestamp of when the token was last updated.

## Other responses

- `4XX`: The request couldn't be processed. For example, a parameter is invalid, the resource doesn't exist, or you don't have permission. The body is a problem details object (RFC 9457).
- `5XX`: Something went wrong on nullplatform's side. The body is a problem details object (RFC 9457).

## Changes

- **2026-10-22** `3d300f7f8452`: 1 info
  - added the new optional request property `expires_in`
- **2026-10-15** `728d4df70ca1`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/nullplatform/apis/nullplatform-api/changes/pat/:id/patch.md)

---

[API](https://skmtc.dev/nullplatform/apis/nullplatform-api.md) - [All operations](https://skmtc.dev/nullplatform/apis/nullplatform-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nullplatform/apis/nullplatform-api/revisions/d3f66bc633d4?raw)