---
title: "Login or refresh token"
method: POST
path: "/auth/v1/token"
tags: ["Auth"]
---

# Login or refresh token

`POST /auth/v1/token`

## Request

- Base URL: `https://api.run402.com`
- URL: `https://api.run402.com/auth/v1/token`
- Auth: API key in header `apikey`

## Request body

- union
  - object
    - `email` string, email, required
    - `password` string, required
  - object
    - `refresh_token` string, required
    - `grant_type` 'refresh_token', required
  - object
    - `grant_type` 'magic_link', required
    - `token` string, required: Single-use token delivered to the user's email inbox via POST /auth/v1/magic-link.
  - object
    - `grant_type` 'email_code', required
    - `challenge_id` string, uuid, required: Opaque handle returned by a code/both request; not a credential.
    - `code` string, required: Secret six-digit credential delivered by email.

## Response `200`

Token issued

- AuthSessionResponse
  - `access_token` string, required
  - `token_type` 'bearer', required
  - `expires_in` integer, required
  - `refresh_token` string, required
  - `user` object, required
    - `id` string, uuid, required
    - `email` string, email, required
    - `email_verified_at` string, date-time, nullable
    - `display_name` string, nullable
    - `avatar_url` string, nullable
  - `elevation_required` boolean: True when project_admin was downgraded until passkey auth.
  - `required_method` 'passkey'
  - `effective_role` 'authenticated'
  - `intended_role` 'project_admin'
  - `provider` string
  - `magic_link` object
    - `intent` 'signin' | 'invite' | 'claim' | 'recovery'
    - `client_state` string, nullable
    - `state_source` 'anonymous' | 'service_key'
    - `state_trusted` boolean
    - `delivery` 'link' | 'code' | 'both'
    - `verified_with` 'link' | 'email_code'

## Other responses

- `401`: Missing or invalid authentication. Run402-originated JSON bodies use the canonical ErrorEnvelope.

---

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