Authentication

Learn how to authenticate with the ShellHub API using API keys, JWT tokens, and OAuth2.

// Authentication Methods

ShellHub supports multiple authentication methods depending on your use case:

Method	Use Case	Expiry
API Key	Server-to-server, CI/CD, scripts	Never (until revoked)
JWT Token	User sessions, frontend apps	1 hour (refreshable)
OAuth2	Third-party integrations	Configurable

// API Keys

API keys are the simplest way to authenticate with ShellHub. They're ideal for server-side applications, automation scripts, and CI/CD pipelines.

Creating an API Key

Navigate to Settings → API Keys in your dashboard

Click "Create API Key"

Choose a name and select permissions (scopes)

Copy the key immediately - it won't be shown again

Using API Keys

Include your API key in the Authorization header:

# Using Bearer token format
curl https://api.shellhub.app/v1/clouds \
  -H "Authorization: Bearer ic_live_abc123xyz..."

# Alternative: Using X-API-Key header
curl https://api.shellhub.app/v1/clouds \
  -H "X-API-Key: ic_live_abc123xyz..."

Key Types

Live Keys

ic_live_...

Production keys with full access to your account. Use in production environments only.

Test Keys

ic_test_...

Sandbox keys for development and testing. Operations don't affect production resources.

Permission Scopes

Scope	Access
`clouds:read`	List and view clouds
`clouds:write`	Create, update, delete clouds
`agents:read`	List and view agents
`agents:write`	Deploy, update, delete agents
`agents:invoke`	Call agent endpoints
`chains:*`	Full access to agent chains
`billing:read`	View invoices and usage
`admin:*`	Full account access (use with caution)

Security Warning: Never expose API keys in client-side code, public repositories, or logs. Use environment variables and secret management tools to store keys securely.

// JWT Tokens

JWT (JSON Web Tokens) are used for user sessions and frontend applications. They provide short-lived access and can be refreshed without requiring the user to re-authenticate.

Obtaining a Token

# Login to get access and refresh tokens
curl -X POST https://api.shellhub.app/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your-password"
  }'

# Response
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "rt_abc123...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Refreshing Tokens

Access tokens expire after 1 hour. Use the refresh token to get a new access token:

curl -X POST https://api.shellhub.app/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "rt_abc123..."
  }'

Token Structure

ShellHub JWTs contain the following claims:

{
  "sub": "user_abc123",           // User ID
  "email": "user@example.com",    // Email
  "org": "org_xyz789",            // Organization ID
  "scopes": ["clouds:*", "agents:*"],  // Permissions
  "iat": 1705312800,              // Issued at
  "exp": 1705316400,              // Expires at
  "iss": "https://api.shellhub.app"  // Issuer
}

// OAuth2 Integration

For third-party integrations, ShellHub supports OAuth2 with Authorization Code flow. This allows users to grant your application access to their ShellHub account.

OAuth2 Flow

[1]

Redirect to Authorization

Send user to ShellHub authorization page

[2]

User Grants Permission

User logs in and approves your app

[3]

Receive Authorization Code

User is redirected back with a code

[4]

Exchange for Tokens

Exchange code for access/refresh tokens

[5]

Access API

Use access token to make API calls

Example Implementation

# Step 1: Build authorization URL
const authUrl = `https://auth.shellhub.app/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://yourapp.com/callback&
  response_type=code&
  scope=clouds:read agents:read&
  state=random_state_string`;

# Step 4: Exchange code for tokens
curl -X POST https://api.shellhub.app/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "code": "AUTH_CODE_FROM_CALLBACK",
    "redirect_uri": "https://yourapp.com/callback"
  }'

To create an OAuth2 application, visit Settings → OAuth Applications in your dashboard.

// Security Best Practices

Use Least Privilege

Only request the scopes your application needs. A deployment script doesn't need billing access, for example.

Rotate Keys Regularly

Rotate API keys every 90 days. You can have multiple active keys to enable zero-downtime rotation.

Use Environment Variables

Store credentials in environment variables or a secret manager (AWS Secrets Manager, HashiCorp Vault, etc.). Never hardcode keys.

Monitor Key Usage

Enable audit logging to track API key usage. Set up alerts for unusual patterns that might indicate a compromised key.

IP Allowlisting

Restrict API keys to specific IP addresses or CIDR ranges. This prevents use of stolen keys from unauthorized locations.

// SDK Examples

Python

from shellhub import ShellHub

client = ShellHub(api_key="ic_live_abc123...")
clouds = client.clouds.list()

Node.js

import { ShellHub } from '@shellhub/sdk';

const client = new ShellHub({ apiKey: 'ic_live_abc123...' });
const clouds = await client.clouds.list();