> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pgw.sipmicro.services/llms.txt
> Use this file to discover all available pages before exploring further.

# Sign in with a Bearer token

> Let apps register with a short-lived access token from your sign-in service, so that they never hold a SIP password.

An app behind your own sign-in, such as a browser softphone, shouldn't need a SIP password as well. With Bearer tokens, your sign-in service issues the app a short-lived token for the user. The app sends the token in its REGISTER, pgw checks it, and pgw registers at the PBX with the user's stored password.

This works only on a [managed mode](https://docs.pgw.sipmicro.services/upstreams/managed-mode.md) upstream, because pgw must hold the password that the app doesn't have.

## Before you begin

* A managed upstream with its users. See [Set up managed mode](https://docs.pgw.sipmicro.services/upstreams/set-up-managed-mode.md).
* A sign-in service that can sign JSON Web Tokens with an ES256 key and publish its public keys at an HTTPS URL.

## Turn on Bearer tokens

**1. Turn on Bearer tokens for the managed upstream**

Set `--app-auth` to `both` to accept a token or the user's password, or to `bearer` to accept only a token.

```bash theme={null}
pgw upstream update --id <upstream-id> --app-auth both --bearer-issuer https://id.example.com --bearer-audience pgw --bearer-jwks-url https://id.example.com/.well-known/jwks.json
```

**2. Issue tokens that pgw accepts**

| Part | Requirement |
| - | - |
| Signature | ES256, with a P-256 key that the JSON Web Key Set at `--bearer-jwks-url` holds |
| Header | `alg` `ES256`, `typ` `at+jwt`, and the key's `kid` |
| `iss` | Exactly `--bearer-issuer` |
| `aud` | `--bearer-audience`, alone or in a list |
| `sub` | The user's SIP URI, such as `sip:1001@pbx.example.com`. Its user and host must match the REGISTER's To URI. |
| `exp`, `iat` | Required. `nbf` is optional. pgw allows 30 seconds of clock difference. |
| Size | At most 8 KiB |

**3. Send the token from the app**

In each REGISTER, send `Authorization: Bearer <token>`. pgw checks the token only when the app registers. pgw then renews at the PBX without the token, so a token lifetime of a few minutes is enough.

## Check that it works

Register the app with a token, then run `pgw binding list`. The list shows a binding for the user in the token's `sub`.

## If it doesn't work

| Answer to the REGISTER | Cause |
| - | - |
| `401` with `error="invalid_token"` | The token is invalid or expired, or its user is unknown or disabled. With `log_level: debug`, pgw logs `bearer token refused` with the check that failed. |
| `403 Forbidden` | The token's `sub` names a different user from the one in the REGISTER's To URI. |
| `500` with `Retry-After: 5` | pgw can't fetch the keys at `--bearer-jwks-url`. |

The first two count toward the [REGISTER ban](https://docs.pgw.sipmicro.services/security.md#register-ban).

## Sign a user out

Because pgw checks a token only when the app registers, an expired token doesn't sign anyone out. pgw keeps the registration at the PBX alive without it. When a user signs out of your service, tell pgw:

```bash theme={null}
pgw user revoke --upstream <upstream-id> 1001
```

Your sign-in service can do the same with `POST /api/v1/upstreams/{id}/revocations`.

## How pgw handles signing keys

pgw fetches the key set over HTTPS and refreshes it every hour. When a token is signed with a key that pgw doesn't know, pgw fetches the set again, at most once a minute, so a new signing key works as soon as you publish it. pgw never logs a token.

## Next steps

> [card] [Web apps](https://docs.pgw.sipmicro.services/apps/web.md)
>
> Connect a browser softphone, the usual client for token sign-in.

> [card] [Managed mode](https://docs.pgw.sipmicro.services/upstreams/managed-mode.md)
>
> Review how pgw keeps registrations alive without the app.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.