​
Using the Aptly API

Aptly provides a secure and scalable REST API for interacting with your organization’s delegation of authority and signatory management data. This guide covers:
  • API environments
  • Authentication
  • Request structure
  • Common errors and responses
  • Helpful tools

​
🌐 Environments

Aptly supports both US and EU regions, each with staging and production environments. Choose the environment that aligns with your organization’s data residency and compliance requirements.

​
Environment Base URLs

RegionEnvironmentApp Base URLAPI Base URL Prefix
USProductionhttps://app.us.aptlydone.comhttps://api.us.aptlydone.com
USStaginghttps://staging.app.us.aptlydone.comhttps://dev.api.us.aptlydone.com
EUProductionhttps://app.eu.aptlydone.comhttps://api.eu.aptlydone.com
EUStaginghttps://staging.app.eu.aptlydone.comhttps://dev.api.eu.aptlydone.com
Each service (e.g., auth, decision, settings) is available under its own sub-path. Example: 
https://dev.api.us.aptlydone.com/decision/v1/decisions

​
🔐 Authentication

Aptly uses token-based authentication. Tokens are scoped to your account and environment.

​
To authenticate:

  1. Use the Auth service to generate a token.
  2. Pass the token as a bearer token in the Authorization header:
Authorization: Bearer YOUR_TOKEN_HERE
Tokens expire after a set period. Rotate them regularly or implement refresh logic.

​
🧪 Testing Your Requests

You can use tools like:

​
Example curl request:

curl -X POST https://dev.api.us.aptlydone.com/decision/v1/decisions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Approve Marketing Spend",
        "category": "Marketing",
        "requiresApproval": true
      }'

​
🚨 Error Handling

Aptly APIs return standard HTTP status codes and structured error messages.
CodeMeaning
200Success
201Created
400Bad request
401Unauthorized
403Forbidden
404Not found
500Internal server error

​
Example error response:

{
  "error": "Invalid delegation",
  "details": "Missing required field: decisionId"
}

​
🧾 Versioning

Aptly APIs are versioned using the URL path. Example: 
/decision/v1/delegations
Major breaking changes will increment the version (e.g., v2). Minor changes may be backward-compatible and reflected in the schema or changelog.
Have questions or want to request an endpoint?
Reach out to [email protected]