Skip to main content
Infrahub supports multiple authentication methods for API access. All authenticated requests require credentials to be sent with each API call.

​
Authentication Methods

​
JWT Tokens

JSON Web Tokens (JWT) are the primary authentication method for user sessions. JWTs provide short-lived access tokens and long-lived refresh tokens.

​
Login with Username and Password

Endpoint: POST /api/auth/login 
curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "infrahub"
  }'
Response: 
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
Access tokens are valid for the duration configured in SETTINGS.security.access_token_lifetime (default: 3600 seconds / 1 hour). Refresh tokens are valid for SETTINGS.security.refresh_token_lifetime.

​
Using Access Tokens

Include the access token in the Authorization header: 
curl http://localhost:8000/api/info \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
For GraphQL requests: 
curl -X POST http://localhost:8000/graphql/main \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { InfraDevice { edges { node { id name { value } } } } }"
  }'

​
Refreshing Access Tokens

When an access token expires, use the refresh token to obtain a new access token. Endpoint: POST /api/auth/refresh 
curl -X POST http://localhost:8000/api/auth/refresh \
  -H "Authorization: Bearer <refresh_token>"
Response: 
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

​
Logout

Invalidate the current refresh token and session. Endpoint: POST /api/auth/logout 
curl -X POST http://localhost:8000/api/auth/logout \
  -H "Authorization: Bearer <access_token>"

​
API Keys

API keys provide long-lived authentication suitable for service accounts and automation.

​
Creating an API Key

API keys are created through the GraphQL API: 
mutation {
  InfrahubAccountTokenCreate(
    data: {
      name: { value: "automation-token" }
      account: { id: "<account-id>" }
    }
  ) {
    ok
    object {
      token {
        value
      }
    }
  }
}
Important: The token value is only displayed once during creation. Store it securely.

​
Using API Keys

Include the API key in the X-INFRAHUB-KEY header: 
curl http://localhost:8000/api/info \
  -H "X-INFRAHUB-KEY: your-api-key-here"
For GraphQL: 
curl -X POST http://localhost:8000/graphql/main \
  -H "X-INFRAHUB-KEY: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { InfraDevice { edges { node { id name { value } } } } }"
  }'

​
OAuth 2.0

Infrahub supports OAuth 2.0 for delegated authentication with external providers.

​
Supported Providers

  • Google OAuth 2.0
  • Custom OAuth 2.0 providers

​
Authorization Flow

  1. Initiate Authorization
Endpoint: GET /api/oauth2/{provider_name}/authorize Redirect users to this endpoint to begin the OAuth flow: 
http://localhost:8000/api/oauth2/google/authorize?final_url=/
  1. Handle Callback
Endpoint: GET /api/oauth2/{provider_name}/token After user authorization, the provider redirects to this endpoint with state and code parameters. Infrahub exchanges the code for tokens and returns: 
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "final_url": "/"
}

​
Configuration

Configure OAuth providers in your Infrahub settings: 
SETTINGS.security.oauth2_providers = [
    SecurityOAuth2Google(
        name="google",
        client_id="your-client-id",
        client_secret="your-client-secret",
        scopes=["openid", "email", "profile"]
    )
]

​
OIDC (OpenID Connect)

Infrahub supports OIDC for standards-based authentication.

​
Authorization Flow

  1. Initiate Authorization
Endpoint: GET /api/oidc/{provider_name}/authorize 
http://localhost:8000/api/oidc/google/authorize?final_url=/
  1. Handle Callback
Endpoint: GET /api/oidc/{provider_name}/token Returns JWT tokens after successful authentication.

​
Configuration

SETTINGS.security.oidc_providers = [
    SecurityOIDCGoogle(
        name="google",
        client_id="your-client-id",
        client_secret="your-client-secret",
        discovery_url="https://accounts.google.com/.well-known/openid-configuration"
    )
]

​
Authentication Implementation Details

​
JWT Token Structure

Access tokens contain: 
{
  "sub": "account-id",
  "iat": 1704067200,
  "nbf": 1704067200,
  "exp": 1704070800,
  "fresh": false,
  "type": "access",
  "session_id": "550e8400-e29b-41d4-a716-446655440000"
}
Refresh tokens contain: 
{
  "sub": "account-id",
  "iat": 1704067200,
  "nbf": 1704067200,
  "exp": 1706659200,
  "fresh": false,
  "type": "refresh",
  "session_id": "550e8400-e29b-41d4-a716-446655440000"
}

​
Account Status Validation

All authentication methods validate that the account status is ACTIVE. Deactivated accounts receive a 401 Unauthorized response. See /home/daytona/workspace/source/backend/infrahub/auth.py:65 for implementation details.

​
Security Settings

Configure authentication behavior in your settings: 
SETTINGS.security.secret_key = "your-secret-key"  # Used for JWT signing
SETTINGS.security.access_token_lifetime = 3600    # 1 hour
SETTINGS.security.refresh_token_lifetime = 2592000  # 30 days

​
Authentication Priority

When multiple authentication methods are provided, Infrahub checks them in this order:
  1. API key (X-INFRAHUB-KEY header)
  2. JWT token (Authorization: Bearer header)
  3. JWT token (cookie)
  4. Anonymous access (if enabled for GET/OPTIONS requests)
See /home/daytona/workspace/source/backend/infrahub/api/dependencies.py:92 for implementation.

​
Error Responses

​
Invalid Credentials

{
  "errors": ["Incorrect password"]
}

​
Expired Token

{
  "errors": ["Expired Signature"]
}

​
Invalid Token

{
  "errors": ["Invalid token"]
}

​
Account Deactivated

{
  "errors": ["This account has been deactivated"]
}

​
Best Practices

  1. Use API Keys for Automation - Service accounts and CI/CD should use API keys
  2. Rotate Tokens Regularly - Implement token rotation for long-running applications
  3. Store Tokens Securely - Never commit tokens to version control
  4. Use HTTPS - Always use HTTPS in production to protect tokens in transit
  5. Implement Token Refresh - Handle token expiration gracefully in client applications
  6. Scope API Keys - Create separate API keys for different services or environments

Build docs developers (and LLMs) love

Get started for freeTalk to us