Skip to main content
All requests to the Poelis Public API require authentication using a REST API Key. REST 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 a REST API Key

  1. Log in to the Poelis web application ↗︎
  2. Navigate to Settings ↗︎ → Manage REST API Keys ↗︎
  3. Click Create REST 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!
REST API keys are sensitive credentials. Store them securely and never commit them to version control.

​
Using Your REST API Key

Include your REST 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"

​
REST API Key Format

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

​
Key Scoping

REST 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 REST API keys periodically, especially if they may have been compromised

Use Different Keys

Create separate keys for different usecases

Monitor Usage

Review REST API key usage in your dashboard to detect unusual activity

​
Key Management

​
Creating Multiple Keys

You can create multiple REST 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 ↗︎ → Manage REST 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 REST 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