API authentication

2 min read Updated 1 month ago

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:

  1. Navigate to Settings in your user menu
  2. Click on API keys in the sidebar
  3. Click Create new key
  4. Enter a descriptive name for your token
  5. 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