Skip to main content
All requests to the Poelis Public API require authentication using an API Key. API keys are organization-scoped and provide access to all resources within your organization. New to the API? Start with the Quick Start to make your first request.

​
Getting an API Key

  1. Log in to the Poelis web application ↗︎
  2. Navigate to Settings ↗︎ → API Keys ↗︎
  3. Click Create API Key
  4. Give your key a descriptive name (e.g., “Production Integration”, “CI/CD Pipeline”)
  5. Copy the key immediately - it won’t be shown again!
API keys are sensitive credentials. Store them securely and never commit them to version control.

​
Using Your API Key

Include your API key in the Authorization header of every request using the Bearer token format: 
Authorization: Bearer <poelis_api_YOUR_KEY_HERE>

​
Example Request

curl -X GET "https://api.poelis.com/v1/public/workspaces" \
  -H "Authorization: Bearer poelis_api_yyRCEbuLi8ugnBWNixCZQL4xKlLKBh-Gi_6zFf4CCIE" \
  -H "Content-Type: application/json"

​
API Key Format

API keys follow this format:
  • Prefix: poelis_api_
  • Length: Variable (typically 40-60 characters)
  • Example: poelis_api_yyRCEbuLi8ugnBWNixCZQL4xKlLKBh-Gi_6zFf4CCIE

​
Key Scoping

API keys are organization-scoped, meaning:
  • ✅ Access to all workspaces in your organization
  • ✅ Access to all products, items, and properties within those workspaces
  • ❌ No access to resources outside your organization
  • ❌ No access to other organizations’ data

​
Security Best Practices

Store Securely

Use environment variables or secret management tools (e.g., AWS Secrets Manager, HashiCorp Vault)

Rotate Regularly

Rotate your API keys periodically, especially if they may have been compromised

Use Different Keys

Create separate keys for different usecases

Monitor Usage

Review API key usage in your dashboard to detect unusual activity

​
Key Management

​
Creating Multiple Keys

You can create multiple API keys for different purposes:
  • Production: For live integrations
  • CI/CD: For automated pipelines
  • Monitoring: For health checks and monitoring tools

​
Revoking Keys

If a key is compromised or no longer needed:
  1. Go to Settings ↗︎ → API Keys ↗︎
  2. Find the key you want to revoke
  3. Click Revoke
  4. The key will be immediately invalidated
Revoking a key will immediately break all integrations using that key. Make sure to update your applications before revoking.

​
Error Responses

If your API key is missing/invalid/revoked, the API returns 401 Unauthorized with the standard error body format. See Response Format and Status Codes for canonical examples.

​
Next Steps