# Auth

No valid credentials: nobody signed in, an expired session, a bad token or secret. 401.

Pattern: `auth.*` (this page) · Raised with: [`fail()`](https://www.prongs.dev/docs/profiles/errors.md) · Intents: [4](#intents) · Statuses: `401`

## Intents

| Intent | Status | Use it for |
|---|---|---|
| [`auth.required`](https://www.prongs.dev/docs/intents/auth/required.md) | `401` | Nobody is signed in, and this needs a signed-in user |
| [`auth.expired`](https://www.prongs.dev/docs/intents/auth/expired.md) | `401` | The caller was signed in, but the session or link has expired |
| [`auth.signin`](https://www.prongs.dev/docs/intents/auth/signin.md) | `401` | A sign-in with the wrong email or password |
| [`auth.invalid`](https://www.prongs.dev/docs/intents/auth/invalid.md) | `401` | A wrong credential: a bad API token, webhook signature or preview secret |

## Raising one

Name what went wrong. The intent sets the status, the message the caller sees, and any log it writes.

```ts
// Nobody is signed in, and this needs a signed-in user
return fail('auth.required');

// The caller was signed in, but the session or link has expired
return fail('auth.expired');

// A sign-in with the wrong email or password
return fail('auth.signin');

// A wrong credential: a bad API token, webhook signature or preview secret
return fail('auth.invalid', 'Preview secret did not match.');
```

The caller gets (auth.required)

```bash
HTTP 401

{
  "ok": false,
  "error": "Sign in required.",
  "code": "auth.required"
}
```

## Is it an auth error?

Find the row that describes your case, and use the domain on the right.

| If the problem is | Use |
|---|---|
| The caller’s request was wrong: unreadable, incomplete, or a value that breaks a rule. 400 or 422. | [`request.*`](https://www.prongs.dev/docs/intents/request.md) |
| No valid credentials: nobody signed in, an expired session, a bad token or secret. 401. | `auth.*` (this page) |
| Valid credentials, but not allowed to do this. 403. | [`permission.*`](https://www.prongs.dev/docs/intents/permission.md) |
| The thing asked for is not there, as far as the caller may know. 404. | [`record.*`](https://www.prongs.dev/docs/intents/record.md) |
| The request clashes with the current state: it already exists, or it is not possible yet. 409. | [`conflict.*`](https://www.prongs.dev/docs/intents/conflict.md) |
| Too many requests, or an allowance used up. 429. | [`limit.*`](https://www.prongs.dev/docs/intents/limit.md) |
| Our fault or a dependency’s. The caller sees a generic message; the details are logged. 5xx. | [`failure.*`](https://www.prongs.dev/docs/intents/failure.md) |

## For registry authors

**Starter intents.** These are the intents `prongs add errors` puts in your registry, raised with [`fail()`](https://www.prongs.dev/docs/profiles/errors.md). Change the messages to suit your app, and the statuses through the [`status.*`](https://www.prongs.dev/docs/intents/errors.md#status) intents they are built from.