---
title: "Create access token (omniauth)"
method: POST
path: "/users/access-tokens"
tags: ["Public", "AccessTokens"]
---

# Create access token (omniauth)

`POST /users/access-tokens`

## Request

- Base URL: `https://api.purplegrain.com/api/v1`
- URL: `https://api.purplegrain.com/api/v1/users/access-tokens`
- Auth: none declared

Signs in with an identity **the provider vouches for**. `credentials.token` must be the provider's own token
(Google ID token, Facebook user access token, Apple identity token); the API checks it with the provider, checks it
was issued to Purple Grain, and signs in only the account whose email **the provider** returned, which must equal
`info.email` and `uid`. Any other claim, a missing token, or a provider the API cannot verify is a **403**. Returns a
**Doorkeeper** access token in JSON (same shape as `POST /oauth/token`,
plus **`user_id`**). Use **`Authorization: Bearer <access_token>`** on `/api/v1/*`. Prefer **`POST /oauth/token`**
when you have a registered OAuth client and want strict RFC 6749 behavior.

## Request body

- object
  - `provider` string
  - `uid` string
  - `info` object
    - `email` string, email
    - `name` string
  - `credentials` object
    - `scope` string, nullable
    - `token` string, nullable
    - `refresh_token` string, nullable
    - `expires_at` string, date-time, nullable
  - `extra` object
    - `id_token` string

## Response `200`

Success — Doorkeeper token response including `user_id`.

- DoorkeeperAccessTokenResponse: Access token issued by Doorkeeper. The same fields are returned from `POST /oauth/token` (RFC 6749). First-party endpoints (`POST /users/sign-in`, `POST /users/access-tokens`) add `user_id` for convenience.
  - `access_token` string, required: Opaque bearer token. Send as header Authorization: Bearer {token} on /api/v1/* routes.
  - `token_type` string, required
  - `expires_in` integer: Lifetime of the access token in seconds.
  - `refresh_token` string, nullable: Present when the client and grant type allow refresh tokens.
  - `scope` string: Granted scopes (space-separated).
  - `user_id` string, uuid, nullable: Only returned by first-party JSON endpoints (`/users/sign-in`, `/users/access-tokens`), not by `POST /oauth/token`.
  - `actor_id` string, uuid, nullable: The acting entity's id (first-party endpoints only). Equals `user_id` today; becomes the Organization id when a token is scoped to act for an organization.
  - `actor_type` 'User' | 'Organization', nullable: Polymorphic type of `actor_id` (first-party endpoints only).

## Other responses

- `403`: Invalid request

---

[API](https://skmtc.dev/purplegrain/apis/purple-grain-api.md) · [All operations](https://skmtc.dev/purplegrain/apis/purple-grain-api/llms.txt) · [OpenAPI document](https://skmtc.dev/purplegrain/apis/purple-grain-api/revisions/06540345bbbc?raw)