Authentication

Authentication methods for Infrahub APIs including JWT, API keys, and OAuth

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=/

2. 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=/

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