# OAuth

## Retrieve the Authorization Server Metadata

`GET /.well-known/oauth-authorization-server`

Retrieve the OAuth 2.0 Authorization Server Metadata describing this
authorization server's endpoints and capabilities, as defined by
[RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414).

The response only advertises capabilities that are actually implemented.
There is no authorization endpoint, no dynamic client registration, and
no token revocation or introspection endpoint, so those fields are
absent.

This endpoint is unauthenticated.

### Responses

#### 200 — The authorization server's metadata. See https://datatracker.ietf.org/doc/html/rfc8414#section-2 for the meaning of each field.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `issuer` | string | Yes | The authorization server's issuer identifier. Matches the `iss` claim of every token we issue. When authenticating with `private_key_jwt`, this is also the value of the client assertion's `aud` claim. |
| `token_endpoint` | string | Yes | URL of the OAuth 2.0 Token Endpoint. |
| `jwks_uri` | string | Yes | URL of the JSON Web Key Set (JWKS) document containing the keys that sign our access tokens. |
| `grant_types_supported` | string[] | Yes | List of the supported OAuth 2.0 grant type values. |
| `token_endpoint_auth_methods_supported` | string[] | Yes | List of client authentication methods supported by the Token Endpoint. |
| `token_endpoint_auth_signing_alg_values_supported` | string[] | Yes | List of JWS signing algorithms supported by the Token Endpoint for the signature on the JWT used to authenticate the client at the Token Endpoint for the `private_key_jwt` authentication method. |

---

## Get a token

`POST /oauth/token`

Get an access token that can be used with the Gigs API.

## Authentication

Clients authenticate using one of the following methods.

### `client_secret_basic`

HTTP Basic authentication using the client credentials:

```
Authorization: Basic <base64(client_id:client_secret)>
```

### `private_key_jwt`

A signed JWT client assertion in the request body (OIDC Core 1.0 §9):

```
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion=<signed JWT>
```

No `Authorization` header is sent. The assertion's `iss` and `sub`
claims must equal the client_id; `aud` must equal
`https://auth.gigs.com`; and the assertion lifetime must not exceed
300 seconds.

### Body

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `grant_type` | client_credentials | Yes | The grant type to use. |
| `scope` | string | No | The scope of access requested for the `client_credentials` grant type. Whether this parameter is required depends on the application. Format: `project:{project_id}`. |
| `client_assertion_type` | urn:ietf:params:oauth:client-assertion-type:jwt-bearer | No | The type of client assertion used to authenticate the client. Required when authenticating with `private_key_jwt`. |
| `client_assertion` | string | No | A signed JWT proving possession of the client's private key. Required when `client_assertion_type` is `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`. |

### Responses

#### 200 — Returns an access token which can be used with the Gigs API.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `access_token` | string | Yes | The access token which grants access to the Gigs API. Must not be parsed or modified. Should not be persisted. |
| `expires_in` | integer | Yes | The lifetime in seconds of the access token. |
| `token_type` | string | Yes | The type of the access token is always `Bearer`. |

#### 400 — Invalid request errors arise when the request was malformed or was missing required properties.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `error` | string | Yes | A single [error code](https://developers.gigs.com/api/error-handling). |
| `error_description` | string | Yes | Human-readable description providing additional information, used to assist in understanding the error that occurred. |

#### 401 — Unauthorized errors arise when the client is invalid or unknown.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `error` | string | Yes | A single [error code](https://developers.gigs.com/api/error-handling). |
| `error_description` | string | Yes | Human-readable description providing additional information, used to assist in understanding the error that occurred. |

#### 429 — Too-many requests errors arise when the client has sent too many requests in a given amount of time and was rate-limited.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `error` | string | Yes | A single [error code](https://developers.gigs.com/api/error-handling). |
| `error_description` | string | Yes | Human-readable description providing additional information, used to assist in understanding the error that occurred. |

---
