API authentication
API authentication
The Ploi Cloud API uses OAuth2 token-based authentication. All API requests must include a valid Bearer token.
Getting your API token
To create an API token:
- Navigate to Settings in your user menu
- Click on API keys in the sidebar
- Click Create new key
- Enter a descriptive name for your token
- Copy the generated token immediately - it will only be shown once
Using your token
Include your token in the Authorization header:
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://ploi.cloud/api/v1/applications
Required headers
Every request needs two headers: Authorization: Bearer YOUR_API_TOKEN and a User-Agent.
Our edge network rejects requests that arrive without a User-Agent, or with the generic default some HTTP libraries send, before they ever reach the API. Python's built-in urllib is the usual culprit, since it identifies itself as Python-urllib/3.x. When that happens you get a 403 with error code: 1010, or an HTML challenge page instead of JSON.
curl, Python requests, Guzzle and most SDKs already send a header that gets through. If you write your own client, set a descriptive value such as my-deploy-script/1.0:
import urllib.request
req = urllib.request.Request(
"https://ploi.cloud/api/v1/applications",
headers={
"Authorization": "Bearer YOUR_API_TOKEN",
"Accept": "application/json",
"User-Agent": "my-deploy-script/1.0",
},
)
print(urllib.request.urlopen(req).read().decode())
Token management
You can manage your API tokens from the Settings > API keys page:
- Create tokens: Generate new personal access tokens with custom names
- List tokens: View all your active tokens including creation date and last usage (token values are never shown after creation)
- Revoke tokens: Immediately invalidate tokens you no longer need by clicking the delete button
Token scopes
All tokens have full API access for all teams your user has access too.
API documentation
For complete API endpoint documentation, visit https://ploi.cloud/docs/api