# `AttestoPhoenix.OpenAPI.TokenEndpoint`
[🔗](https://github.com/XukuLLC/attesto_phoenix/blob/v0.19.0/lib/attesto_phoenix/open_api/token_endpoint.ex#L2)

OpenApiSpex operation and schema values for the OAuth 2.0 token endpoint.

This module is available only when the host depends on `:open_api_spex`.
`attesto_phoenix` declares that dependency as optional, so authorization
servers that do not publish an OpenAPI document do not compile or ship
OpenApiSpex.

The first documented request is the RFC 6749 §4.4 `client_credentials`
exchange, because it is the common machine-to-machine token endpoint
integration. The response and error schemas cover Bearer tokens, DPoP-bound
tokens, and the OAuth / DPoP error envelope emitted by
`AttestoPhoenix.Controller.TokenController`.

## Host wiring

Add `operation/1` to the host's `OpenApiSpex.PathItem` for `POST
/oauth/token` and merge `schemas/0` into the host's components.

# `operation`

```elixir
@spec operation(keyword()) :: OpenApiSpex.Operation.t()
```

Returns the OpenApiSpex operation for `POST /oauth/token`.

Options:

  * `:tags` - operation tags, defaulting to `["OAuth 2.0"]`.
  * `:operation_id` - operation id, defaulting to
    `"attestoPhoenixTokenCreate"`.
  * `:summary` - summary text.
  * `:description` - description text.
  * `:security` - OpenAPI security requirements supplied by the host.

The operation intentionally does not name host security-scheme components.
Client authentication is described in the request body and prose, while a
host that defines HTTP Basic or other client-auth security schemes can pass
`security: ...`.

# `request_body`

```elixir
@spec request_body() :: OpenApiSpex.RequestBody.t()
```

Returns the token request body for the media types accepted by the token
controller.

# `responses`

```elixir
@spec responses() :: %{required(integer()) => OpenApiSpex.Response.t()}
```

Returns token endpoint responses keyed by HTTP status.

# `schemas`

```elixir
@spec schemas() :: %{required(String.t()) => OpenApiSpex.Schema.t()}
```

Returns reusable component schemas referenced by `operation/1`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*