---
title: Authentication
description: Get an access token from the token endpoint, with client credentials or as an installed connector.
---

Every request to the API carries an access token in the `Authorization` header:

```http
Authorization: Bearer <access_token>
```

You get the token from `POST https://idp.hydda.one/oauth/token`. A token lives for 600 seconds and comes with no refresh token. Request a new one before it expires.

## As an Application: client credentials

An organization administrator creates the Application and gives you its `client_id` and a client secret. The secret starts with `everest_sk_` and is shown only once. An Application can have two active secrets at a time, so you can roll to a new one without downtime.

Send the request as `application/x-www-form-urlencoded`. Put the credentials in HTTP Basic authentication:

```bash
curl https://idp.hydda.one/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials
```

Or put them in the form body instead. Do not send both.

```bash
curl https://idp.hydda.one/oauth/token \
  -d grant_type=client_credentials \
  -d client_id="$CLIENT_ID" \
  -d client_secret="$CLIENT_SECRET"
```

The response:

```json
{ "access_token": "eyJ…", "token_type": "Bearer", "expires_in": 600 }
```

Do not send a `scope` parameter. The endpoint issues no scopes. What a token can do comes from the roles the Application holds. See [Roles](/guides/roles).

## As an installed connector: the installation-token grant

A connector has no client secret. It signs a short JWT with its private key and exchanges it for a token for one installation.

The JWT is an RFC 7523 client assertion signed with `ES256`:

| Claim | Value |
| --- | --- |
| `iss`, `sub` | The app id. |
| `aud` | `https://idp.hydda.one/oauth/token` |
| `iat`, `exp` | `exp` is at most 300 seconds after `iat`. |
| `jti` | A unique id. An assertion works only once. |

Send it with the installation's id:

```bash
curl https://idp.hydda.one/oauth/token \
  -d grant_type=urn:everest:params:oauth:grant-type:installation-token \
  -d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
  -d client_assertion="$ASSERTION" \
  -d installation_id="$INSTALLATION_ID"
```

The response has the same shape. The token lives for 600 seconds and carries the roles granted to that installation.

## Discovery and signing keys

The identity host publishes its OpenID configuration and its public keys:

- `GET https://idp.hydda.one/.well-known/openid-configuration` lists the token endpoint, the supported grant types and the client authentication methods.
- `GET https://idp.hydda.one/.well-known/jwks.json` returns the keys that sign access tokens.

## Token endpoint errors

The token endpoint answers failures in the OAuth 2.0 format, `{ "error", "error_description" }`, not as problem details.

| `error` | Status | When |
| --- | --- | --- |
| `invalid_request` | 400 | The body is not form-encoded, `grant_type` is missing, a parameter is repeated, or both credential methods are used. |
| `unsupported_grant_type` | 400 | The grant type is not one of the two above. |
| `invalid_scope` | 400 | The request has a `scope` parameter. |
| `invalid_grant` | 400 | The installation is not active, or belongs to another app. |
| `invalid_client` | 401 | The credentials are wrong, revoked or disabled, or the assertion is not valid or was used before. |
| `slow_down` | 429 | More than 60 token requests for one client in 60 seconds. Wait for the `Retry-After` seconds. |

`invalid_client` does not say which check failed, on purpose.

## Revoking access

Revoking a secret, disabling an Application or removing an installation stops new tokens. A token already issued keeps working until it expires, at most 600 seconds later.

## Trying requests from this site

Every operation page in the [API reference](/reference) has a **Try it** panel. Get a token with one of the commands above and paste it into the panel's token field. Pick the server for your environment. The request goes through this site's proxy to that server.