Authentication

The Powerverse Platform API supports multiple authentication methods to fit different use cases. Choose the method that best suits your integration needs.

Authentication Methods Overview

Method	Use Case	Token Lifetime
JWT Bearer Token	User-context requests, web/mobile apps	1 hour
API Key	Server-to-server, automated systems	Long-lived
OAuth 2.0	Third-party integrations	Configurable

JWT Bearer Tokens

Bearer tokens are the primary authentication method for user-context requests.

Obtaining a Token

Password Grant (User Login)

curl -X POST "https://platform.powerverse.com/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "password",
    "username": "operator@example.com",
    "password": "your-password",
    "client_id": "your-client-id"
  }'

Client Credentials Grant (Service Account)

curl -X POST "https://platform.powerverse.com/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "your-client-id",
    "client_secret": "your-client-secret"
  }'

Token Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJvcHJfYWJjMTIzIiwiZXhwIjoxNzA0MDY3MjAwfQ.signature",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_xxxxxxxxxxxxxxxxxxxxxx"
}

Using the Token

Include the token in the Authorization header:

curl -X GET "https://platform.powerverse.com/inventory-service/sites" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Refreshing Tokens

Before your token expires, use the refresh token to obtain a new access token:

curl -X POST "https://platform.powerverse.com/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "rt_xxxxxxxxxxxxxxxxxxxxxx",
    "client_id": "your-client-id"
  }'

Token Refresh Best Practice

Refresh your token when ~80% of its lifetime has passed, rather than waiting for it to expire.

API Keys

API keys provide a simpler authentication method for server-to-server communication.

Obtaining an API Key

API keys are provisioned through the developer portal or by contacting api-support@powerverse.com.

Key Format

API keys follow this format:

• Live/Production: ak_live_xxxxxxxxxxxxxxxxxxxx
• Test/Sandbox: ak_test_xxxxxxxxxxxxxxxxxxxx

Using API Keys

Include the key in the X-API-Key header:

curl -X GET "https://platform.powerverse.com/inventory-service/assets" \
  -H "X-API-Key: ak_live_xxxxxxxxxxxxxxxxxxxx"

API Key Security

Keep Your Keys Secret

• Never expose API keys in client-side code
• Don't commit keys to version control
• Rotate keys immediately if compromised
• Use environment variables for key storage

Key Rotation

To rotate an API key:

1. Generate a new key in the developer portal
2. Update your applications to use the new key
3. Verify the new key works correctly
4. Revoke the old key

OAuth 2.0

For third-party integrations, we support OAuth 2.0 with the Authorization Code flow.

Supported Flows

• Authorization Code - Web applications with server-side component
• Authorization Code with PKCE - Mobile and single-page applications

OAuth Endpoints

Endpoint	URL
Authorization	https://auth.powerverse.com/oauth2/authorize
Token	https://auth.powerverse.com/oauth2/token
Revoke	https://auth.powerverse.com/oauth2/revoke
User Info	https://auth.powerverse.com/oauth2/userinfo

Available Scopes

Scope	Description
read:sites	Read site information
write:sites	Create and modify sites
read:assets	Read asset information
write:assets	Create and modify assets
read:schedules	Read schedule information
write:schedules	Create and modify schedules
read:sessions	Read session information
read:events	Read event data
admin	Full administrative access

Authorization Code Flow

Step 1: Redirect to Authorization

https://auth.powerverse.com/oauth2/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://yourapp.com/callback&
  scope=read:sites%20read:assets&
  state=random-state-string

Step 2: Exchange Code for Token

After the user authorizes, they're redirected to your callback URL with a code:

curl -X POST "https://auth.powerverse.com/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://yourapp.com/callback" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

PKCE Flow (for Public Clients)

For mobile apps and SPAs, use PKCE to protect the authorization code:

// Generate code verifier and challenge
const codeVerifier = generateRandomString(64);
const codeChallenge = base64UrlEncode(sha256(codeVerifier));

// Include in authorization request
const authUrl = `https://auth.powerverse.com/oauth2/authorize?
  response_type=code&
  client_id=${clientId}&
  redirect_uri=${redirectUri}&
  scope=${scope}&
  code_challenge=${codeChallenge}&
  code_challenge_method=S256&
  state=${state}`;

Security Best Practices

Token Storage

Platform	Recommended Storage
Web (SPA)	Memory only, or HttpOnly cookies
Mobile	Secure keychain/keystore
Server	Environment variables or secret manager

Additional Security Headers

For enhanced security, consider including:

curl -X GET "https://platform.powerverse.com/inventory-service/sites" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Request-ID: unique-request-id" \
  -H "X-Client-Version: 1.0.0"

Error Responses

401 Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired token"
  }
}

Common causes:

• Token has expired
• Token is malformed
• Token was revoked

403 Forbidden

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions for this resource"
  }
}

Common causes:

• Missing required scope
• Resource belongs to another organization
• IP not allowlisted

Next Steps

• Authorization - Learn about permissions and roles
• API Keys - Detailed API key management