Authentication

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:

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:

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.

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

The response:

{ "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.

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:

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 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.