API Authentication

All Piora API requests require authentication. Piora uses Bearer Tokens for API authentication.

Obtaining an API Token

Generate in the Dashboard

1. Log into the Piora Dashboard
2. Go to “Settings” > “API Tokens”
3. Click “Generate New Token”
4. Name the token (e.g., ci-cd-pipeline)
5. Select token permission scopes
6. Click “Create”

Displayed Only Once

The token is only shown once at creation time. Copy it immediately and store it securely. If lost, you’ll need to generate a new token.

Token Permissions

When generating a token, you can select the following permission scopes:

Permission	Description
servers:read	Read server information
servers:write	Manage servers
applications:read	Read application information
applications:write	Manage applications
applications:deploy	Deploy applications
databases:read	Read database information
databases:write	Manage databases
backups:read	Read backup information
backups:write	Manage backups

Least Privilege

We recommend generating separate tokens for each use case and granting only the necessary permissions. For example, a CI/CD pipeline only needs the applications:deploy permission.

Using Tokens

Bearer Token Authentication

Include the token in the Authorization header of every API request:

curl -X GET https://app.piora.dev/api/v1/servers \
  -H "Authorization: Bearer piora_token_xxxxxxxxxxxx"

Language Examples

// Node.js (fetch)
const response = await fetch('https://app.piora.dev/api/v1/servers', {
  headers: {
    'Authorization': 'Bearer piora_token_xxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
});
const data = await response.json();

# Python (requests)
import requests

response = requests.get(
    'https://app.piora.dev/api/v1/servers',
    headers={'Authorization': 'Bearer piora_token_xxxxxxxxxxxx'}
)
data = response.json()

// Go
req, _ := http.NewRequest("GET", "https://app.piora.dev/api/v1/servers", nil)
req.Header.Set("Authorization", "Bearer piora_token_xxxxxxxxxxxx")
resp, _ := http.DefaultClient.Do(req)

Token Management

View Token List

On the “Settings” > “API Tokens” page, you can see all created tokens:

• Token name
• Permission scopes
• Creation date
• Last used time

Revoke a Token

If a token may have been compromised, revoke it immediately:

1. Go to “Settings” > “API Tokens”
2. Find the target token
3. Click “Revoke”
4. Confirm the operation

Once revoked, all requests using that token will immediately receive a 401 Unauthorized response.

Security Best Practices

1. Never hardcode tokens in source code — Use environment variables
2. Never commit tokens to version control — Add tokens to .gitignore
3. Rotate tokens regularly — We recommend every 90 days
4. Use least privilege — Only grant the necessary permission scopes
5. Monitor usage — Regularly review token usage logs

# Use environment variables
export PIORA_API_TOKEN=piora_token_xxxxxxxxxxxx

# Use in your application
curl -H "Authorization: Bearer $PIORA_API_TOKEN" \
  https://app.piora.dev/api/v1/servers

Token Compromise

If you suspect a token has been compromised (e.g., accidentally committed to Git), immediately revoke it and generate a new one.

Error Codes

HTTP Status	Description
401	Token is invalid or expired
403	Token has insufficient permissions
429	Rate limit exceeded