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

# OAuth and authentication types

> Reference for every authentication method RubixKube supports on integrations. API keys, OAuth 2.0, mTLS, signed requests, and more.

Reference for every authentication method RubixKube supports on integrations. Pick the section for the scheme you need, or see the table below for a quick overview.

## Quick overview

| Method                       | Best for                                    | Secret storage                                     |
| ---------------------------- | ------------------------------------------- | -------------------------------------------------- |
| API key or Bearer token      | Simple internal APIs, machine-to-machine    | Vault, per integration                             |
| OAuth 2.0 Authorisation Code | User-scoped actions (Slack, Linear, Notion) | Vault with automated refresh                       |
| OAuth 2.0 Client Credentials | Service-to-service with OAuth               | Vault with automated refresh                       |
| mTLS                         | Private APIs with network-level trust       | Vault with client certificate                      |
| HMAC signed requests         | Webhooks, event ingestion                   | Vault with shared secret                           |
| JWT in header                | APIs that mint short-lived tokens           | Vault with signing key, tokens minted just-in-time |

All secrets live in the workspace secret vault, encrypted at rest, scoped per integration, and never visible in agent prompts or logs.

## API key or Bearer token

The simplest option. A static credential passed in a header or query parameter.

<CardGroup cols={2}>
  <Card title="When to use" icon="circle-check">
    Internal tools, machine-to-machine calls, read-only APIs.
  </Card>

  <Card title="When to avoid" icon="circle-xmark">
    User-scoped actions, anything that needs per-user authorisation, anywhere a key rotation cadence is hard to run.
  </Card>
</CardGroup>

Configure in **Integrations → \[your integration] → Auth**. Set the header name (default `Authorization: Bearer <token>`) or the query parameter if the API is quirky.

## OAuth 2.0 (Authorisation Code)

The standard flow for user-scoped integrations. RubixKube handles the redirect handshake and refresh cycle.

<Steps titleSize="h3">
  <Step title="Register an OAuth app">
    On the upstream tool (Slack, Linear, Atlassian, etc.), create an OAuth application. Set the redirect URL to `https://api.rubixkube.ai/oauth/callback`.
  </Step>

  <Step title="Add client credentials to RubixKube">
    Paste the client ID and client secret into the integration's Auth tab.
  </Step>

  <Step title="Authorise">
    Click **Connect**, sign in on the upstream tool, and approve the scopes RubixKube requests. The refresh token is stored in the vault.
  </Step>

  <Step title="Scope narrowly">
    Request the smallest scope that works. If the upstream offers a dedicated "read" scope, pick that over "read and write".
  </Step>
</Steps>

Refresh tokens rotate automatically. If an upstream invalidates the token (common after 90 days of inactivity), the integration card flags **Reauthorise needed**.

## OAuth 2.0 (Client Credentials)

Service-to-service with OAuth. No user interaction.

Supply the client ID, client secret, and token endpoint URL. Optional scope and audience claims. RubixKube fetches tokens just-in-time and caches them for their lifetime.

## mTLS

For private APIs where you want network-level trust.

<Steps titleSize="h3">
  <Step title="Obtain a client certificate">
    Issue a client cert from your internal CA, scoped to the RubixKube Cloud egress identity.
  </Step>

  <Step title="Upload to the vault">
    In the integration's Auth tab, upload the certificate (PEM) and private key. Configure the expected server certificate chain if needed.
  </Step>

  <Step title="Configure rotation">
    Set a rotation reminder. RubixKube notifies the workspace admin 14 days before the cert expires.
  </Step>
</Steps>

## HMAC signed requests

Common for webhook-style APIs. RubixKube signs each outbound call with a shared secret using HMAC-SHA256 (or SHA512).

Configuration:

* Shared secret in the vault.
* Signed header name (default `X-Signature`).
* Optional timestamp header for replay protection.

## JWT in header

APIs that require a short-lived JWT minted per request. RubixKube supports:

* **HS256 / HS384 / HS512** with a shared secret.
* **RS256 / RS384 / RS512** with an RSA private key.
* **ES256 / ES384** with an EC private key.

Claims (issuer, audience, subject, expiry, custom) are configurable per integration. Tokens are minted just-in-time and never persisted beyond their expiry.

## Secret rotation

All secret types support rotation without downtime.

<AccordionGroup>
  <Accordion title="How rotation works" icon="arrows-rotate">
    Upload the new secret alongside the old one. RubixKube switches to the new secret on the next outbound call and retires the old one after a grace window.
  </Accordion>

  <Accordion title="Scheduled rotation" icon="calendar">
    Configure a rotation cadence per integration. The workspace admin gets notified when a rotation is due.
  </Accordion>

  <Accordion title="Breakglass" icon="key">
    Emergency rotation revokes the old secret immediately. Any in-flight calls fail, future calls use the new secret.
  </Accordion>
</AccordionGroup>

## Audit

Every auth event is audited: token issued, token refreshed, reauthorise required, rotation completed, cert expiring. Audit entries are immutable and retained per your plan.

## Troubleshooting

<AccordionGroup>
  <Accordion title="OAuth loop redirecting indefinitely">
    The redirect URL on the upstream app does not match `https://api.rubixkube.ai/oauth/callback` exactly. Check for trailing slashes or protocol mismatches.
  </Accordion>

  <Accordion title="mTLS handshake fails">
    Most common cause is cert chain mismatch. Upload the intermediate certs into the vault alongside the client cert. Check SNI if the upstream uses multiple virtual hosts.
  </Accordion>

  <Accordion title="HMAC signature rejected">
    Check the header name and the signing algorithm (usually SHA256). Some APIs include the request body hash, others include a timestamp. Match the upstream's canonicalisation exactly.
  </Accordion>
</AccordionGroup>

## Related guides

<CardGroup cols={2}>
  <Card title="Custom REST Integrations" icon="network-wired" href="/integrations/custom-rest">
    Where most auth configuration lives in practice.
  </Card>

  <Card title="Custom MCP Servers" icon="server" href="/integrations/custom-mcp-servers">
    Auth for internal MCP servers works the same way.
  </Card>
</CardGroup>