---
title: "Headless authorization grant"
method: POST
path: "/oauth/authorize/grant"
tags: ["OAuth"]
---

# Headless authorization grant

`POST /oauth/authorize/grant`

## Request

- Base URL: `https://api.purplegrain.com`
- URL: `https://api.purplegrain.com/oauth/authorize/grant`
- Auth: HTTP bearer

Mints an authorization code on behalf of an already-authenticated user.
Because sessions are disabled on the API, the interactive
`GET /oauth/authorize` consent UI cannot establish a resource owner; the
frontend authenticates the user, shows the consent screen, and POSTs the
original authorize params here with the user's **`Authorization: Bearer`**
token. PKCE is enforced exactly as in the standard flow. Returns the
redirect URI (carrying `code` + `state`) for the browser to follow back to
the client, which then exchanges the code at `POST /oauth/token`.

## Request body

- AuthorizationGrantRequest: Authorize parameters for the headless grant. Identical to the query parameters of `GET /oauth/authorize`; sent as a POST body alongside the consenting user's bearer token.
  - `client_id` string, required
  - `response_type` 'code', required
  - `redirect_uri` string, uri, required
  - `scope` string
  - `state` string
  - `code_challenge` string, required: PKCE code challenge (S256).
  - `code_challenge_method` 'S256', required
  - `nonce` string
  - `resource` string, uri: The exact MCP resource URI advertised by discovery. Omission uses that resource for existing clients.

## Response `201`

Authorization code issued.

- AuthorizationGrantResponse: The redirect URI (carrying `code` and `state`) for the browser to follow back to the client.
  - `redirect_uri` string, uri

## Other responses

- `400`: Authorization request is not authorizable (invalid client, redirect URI, scope, or PKCE).
- `401`: Missing or invalid bearer token.

---

[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/29c5c990d66e?raw)