# Auth · Methods

> Which authentication methods a deployment offers, for signing in and for registering.

Which ways in a deployment offers, and to whom. Every registration and sign-in screen should render from these
rather than from a hard-coded list — a client that offers a method the deployment has turned off is a client that
reports "method unavailable" and looks broken.

The settings are one store with two halves. `signIn` governs getting into an existing account;
`registration` governs making a new one. They are separate because the answers usually differ: a
deployment might accept a passphrase for either, but only ever create accounts by emailed link.

Each half is keyed by authentication kind, then by method:
`{ "username": { "passphrase": true, "credential": true } }`.

All three routes are admin-guarded. The public read is the shape a client actually needs, not the store itself.

The whole method-settings object — `{ signIn, registration }` — keyed by authentication kind, then by
method. Reach for this when configuring a deployment; reach for the two halves when rendering one screen.

## Read every method setting

`GET /api/auth/authentication/method`

Guard: admin

Both halves as stored.

### Returns

`{ signIn, registration }`.

### Request (cURL)

```
curl https://example.com/api/auth/authentication/method \
  -H "authorization: Bearer $TOKEN"
```

### Response

```json
{
  "signIn": {
    "username": { "passphrase": true, "credential": true },
    "email": { "passphrase": true, "verification": true, "code": true }
  },
  "registration": {
    "username": { "passphrase": true },
    "email": { "verification": true }
  }
}
```

## Merge a change into the method settings

`POST /api/auth/authentication/method`

Guard: admin

A patch across either half. Keys absent from the body keep the values they had.

### Parameters

- `signIn` _object_ — The sign-in half, keyed by authentication kind.
- `registration` _object_ — The registration half, keyed by authentication kind.

### Returns

Both halves after the merge.

### Request (cURL)

```
curl -X POST https://example.com/api/auth/authentication/method \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{ "signIn": { "username": { "credential": true } } }'
```

### Response

```json
{
  "signIn": { "username": { "passphrase": true, "credential": true } },
  "registration": { "username": { "passphrase": true } }
}
```

## Replace the method settings

`PUT /api/auth/authentication/method`

Guard: admin

Wholesale replacement of both halves. Anything not in the body is gone.

### Parameters

- `signIn` _object_ — The complete sign-in half.
- `registration` _object_ — The complete registration half.

### Returns

The settings as written.

### Request (cURL)

```
curl -X PUT https://example.com/api/auth/authentication/method \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{ "signIn": { "username": { "passphrase": true } }, "registration": {} }'
```

### Response

```json
{
  "signIn": { "username": { "passphrase": true } },
  "registration": {}
}
```

## Reset every method setting

`DELETE /api/auth/authentication/method`

Guard: admin

Back to the framework defaults, both halves.

### Returns

The settings after the reset.

### Request (cURL)

```
curl -X DELETE https://example.com/api/auth/authentication/method \
  -H "authorization: Bearer $TOKEN"
```

### Response

```json
{
  "signIn": { "username": { "passphrase": true } },
  "registration": { "username": { "passphrase": true } }
}
```

Which authentication methods the deployment offers for signing in. Keyed by authentication kind, then by method —
`{ "username": { "passphrase": true, "credential": true } }`. A client that reports "method
unavailable" is reporting this, not a bug in itself.

## Read the sign-in methods

`GET /api/auth/signin/method`

Guard: admin

The settings as stored. Safe to render a form from.

### Returns

The `signIn` half of the method settings.

### Request (cURL)

```
curl https://example.com/api/auth/signin/method \
  -H "authorization: Bearer $TOKEN"
```

### Response

```json
{
  "username": { "passphrase": true, "credential": true },
  "email": { "passphrase": true, "verification": true, "code": true },
  "phone": { "code": true }
}
```

## Merge a change into the sign-in methods

`POST /api/auth/signin/method`

Guard: admin

A patch. Keys absent from the body keep the values they had.

### Parameters

- `<kind>` _object_ — One entry per authentication kind — `email`, `phone`, `username` — holding the methods to enable or disable.
  - `<method>` _boolean_ — Whether that method is offered.

### Returns

The `signIn` settings after the merge.

### Request (cURL)

```
curl -X POST https://example.com/api/auth/signin/method \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{ "username": { "credential": true } }'
```

### Response

```json
{
  "username": { "passphrase": true, "credential": true }
}
```

## Replace the sign-in methods

`PUT /api/auth/signin/method`

Guard: admin

Wholesale replacement. Anything not in the body is gone — which is the difference from `POST`, and the reason to reach for this only when writing the whole settings object.

### Parameters

- `<kind>` _object_ — The complete settings, replacing what was stored.

### Returns

The `signIn` settings as written.

### Request (cURL)

```
curl -X PUT https://example.com/api/auth/signin/method \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{ "username": { "passphrase": true } }'
```

### Response

```json
{
  "username": { "passphrase": true }
}
```

## Reset the sign-in methods

`DELETE /api/auth/signin/method`

Guard: admin

Back to the framework defaults.

### Returns

The `signIn` settings after the reset.

### Request (cURL)

```
curl -X DELETE https://example.com/api/auth/signin/method \
  -H "authorization: Bearer $TOKEN"
```

### Response

```json
{
  "username": { "passphrase": true },
  "email": { "passphrase": true, "verification": true }
}
```

Which authentication methods the deployment offers for registering. Keyed by authentication kind, then by method —
`{ "username": { "passphrase": true, "credential": true } }`. A client that reports "method
unavailable" is reporting this, not a bug in itself.

## Read the registration methods

`GET /api/auth/register/method`

Guard: admin

The settings as stored. Safe to render a form from.

### Returns

The `registration` half of the method settings.

### Request (cURL)

```
curl https://example.com/api/auth/register/method \
  -H "authorization: Bearer $TOKEN"
```

### Response

```json
{
  "username": { "passphrase": true, "credential": true },
  "email": { "passphrase": true, "verification": true, "code": true },
  "phone": { "code": true }
}
```

## Merge a change into the registration methods

`POST /api/auth/register/method`

Guard: admin

A patch. Keys absent from the body keep the values they had.

### Parameters

- `<kind>` _object_ — One entry per authentication kind — `email`, `phone`, `username` — holding the methods to enable or disable.
  - `<method>` _boolean_ — Whether that method is offered.

### Returns

The `registration` settings after the merge.

### Request (cURL)

```
curl -X POST https://example.com/api/auth/register/method \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{ "username": { "credential": true } }'
```

### Response

```json
{
  "username": { "passphrase": true, "credential": true }
}
```

## Replace the registration methods

`PUT /api/auth/register/method`

Guard: admin

Wholesale replacement. Anything not in the body is gone — which is the difference from `POST`, and the reason to reach for this only when writing the whole settings object.

### Parameters

- `<kind>` _object_ — The complete settings, replacing what was stored.

### Returns

The `registration` settings as written.

### Request (cURL)

```
curl -X PUT https://example.com/api/auth/register/method \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{ "username": { "passphrase": true } }'
```

### Response

```json
{
  "username": { "passphrase": true }
}
```

## Reset the registration methods

`DELETE /api/auth/register/method`

Guard: admin

Back to the framework defaults.

### Returns

The `registration` settings after the reset.

### Request (cURL)

```
curl -X DELETE https://example.com/api/auth/register/method \
  -H "authorization: Bearer $TOKEN"
```

### Response

```json
{
  "username": { "passphrase": true },
  "email": { "passphrase": true, "verification": true }
}
```