Authentication

The LegionEdge Platform supports multiple authentication methods to accommodate different use cases -- from server-to-server integrations to user-facing web applications.

Authentication Methods

API Keys

API keys are long-lived credentials intended for server-side use. Each key is scoped to an organization and can be further restricted to specific projects or permissions.

import { LegionEdge } from "@legionedge/sdk";

const client = new LegionEdge({
  apiKey: "le_live_abc123def456",
});

API keys follow the format le_{environment}_{random}, where environment is either live or test.

OAuth 2.0 Tokens

For user-facing applications, the platform implements the OAuth 2.0 authorization code grant with PKCE. This flow issues short-lived access tokens and long-lived refresh tokens.

import { LegionEdge } from "@legionedge/sdk";

const client = new LegionEdge({
  accessToken: "eyJhbGciOiJSUzI1NiIs...",
});

JWT Structure

Access tokens are signed JWTs with the following claims:

{
  "sub": "user_abc123",
  "org": "org_def456",
  "iat": 1700000000,
  "exp": 1700003600,
  "scopes": ["projects:read", "projects:write", "resources:read"],
  "iss": "https://auth.legionedge.com"
}

Tokens expire after 1 hour by default. Use the refresh token to obtain a new access token without re-authenticating.

Session Management

The platform tracks active sessions per user. You can list and revoke sessions programmatically:

// List active sessions
const sessions = await client.auth.sessions.list();

for (const session of sessions.data) {
  console.log(`${session.id} - ${session.ipAddress} - ${session.lastActive}`);
}

// Revoke a specific session
await client.auth.sessions.revoke(sessionId);

// Revoke all sessions except the current one
await client.auth.sessions.revokeAll({ keepCurrent: true });

SSO Integration

The platform supports SSO through SAML 2.0 and OpenID Connect. Configure SSO at the organization level:

1. Navigate to Organization Settings > Authentication > SSO in the dashboard.
2. Select your identity provider (Okta, Azure AD, Google Workspace, or custom SAML/OIDC).
3. Provide the metadata URL or upload the metadata XML.
4. Map identity provider attributes to LegionEdge user fields.

Once enabled, organization members authenticate through your identity provider and are automatically provisioned in the platform.

// Check SSO configuration for an organization
const ssoConfig = await client.organizations.getSsoConfig("org_def456");
console.log(`SSO provider: ${ssoConfig.provider}`);
console.log(`SSO enabled: ${ssoConfig.enabled}`);

Token Refresh

import { LegionEdge } from "@legionedge/sdk";

const client = new LegionEdge({
  clientId: "your_client_id",
  refreshToken: "le_rt_abc123",
  onTokenRefresh: (newTokens) => {
    // Persist the new tokens
    saveTokens(newTokens);
  },
});

// The SDK automatically refreshes expired tokens before making requests
const projects = await client.projects.list();

Rate Limits

Authentication endpoints have their own rate limits:

When rate limited, the API returns 429 Too Many Requests with a Retry-After header.

Next Steps

• Learn about authorization and RBAC for controlling access to resources.
• See the OAuth API reference for the full OAuth flow.