Send every request with a bearer token:
Hermios does not read x-api-key or other headers.

​
API keys

Create one in Settings → MCP & APIs → API keys. You need the API keys and webhooks permission.
  • Role: every key has a role, and the key can do exactly what that role allows. Only roles marked as assignable to API keys are offered. Give each integration its own role with the smallest set of objects it needs.
  • Expiry: 15 days, 30 days, 90 days (default) or 1 year. Hermios never issues a key that lives longer than a year: a longer expiry sent through the API is shortened to one year.
  • The key is shown once. Store it in a secret manager, never in front-end code or a repository.
Revoke a key from the same page as soon as it is no longer needed.

​
OAuth 2.1

Use OAuth when your app acts for a person, so it gets that person’s access instead of a shared key. Discovery documents (public):
  • GET https://api.hermios.app/.well-known/oauth-authorization-server
  • GET https://api.hermios.app/.well-known/oauth-protected-resource
  • GET https://api.hermios.app/.well-known/oauth-protected-resource/mcp (for MCP clients)
  • Response type code, with PKCE S256 required.
  • Grant types: authorization_code, refresh_token (and client_credentials for registered server apps).
  • Dynamically registered clients are public clients (token_endpoint_auth_method: none) and may use authorization_code and refresh_token only.
  • Scopes are api and profile. They label the consent screen; what the token can actually reach is decided by the person’s role in the workspace they pick.
  • Access tokens last 30 minutes. Use the refresh token to get a new one.

​
Permissions in practice

Some actions are deliberately unavailable to tokens. For example, vault secrets can only be revealed by a signed-in member in the app.