Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.orkesta.com.tr/llms.txt

Use this file to discover all available pages before exploring further.

Orkesta uses bearer token authentication. Every API request must include your API key in the Authorization header. Requests without a valid key are rejected with a 401 error.

​
How it works

When you create an API key in your Orkesta workspace, Orkesta generates a unique secret token scoped to your account. You pass this token with every request. Orkesta validates it against your workspace on each call — there are no session cookies or OAuth flows for server-to-server use. You can generate multiple keys with different scopes and expiry dates, and revoke any key at any time without affecting others.

​
Passing your API key

Include your API key as a bearer token in the Authorization header: 
curl -X GET https://api.orkesta.com.tr/v1/accounts \
  -H "Authorization: Bearer YOUR_API_KEY"
All requests must be made over HTTPS. HTTP requests are rejected.
Never hardcode API keys in source code. Use environment variables or a secrets manager.

​
Generating an API key

1

Sign in to your Orkesta workspace

Go to orkesta.com.tr and sign in with your account credentials.
2

Go to Settings → API Keys

In the left sidebar, click Settings, then select API Keys.
3

Create a new key

Click New key. Enter a descriptive name (for example, production-erp-integration) and set an optional expiry date. Select the appropriate scope for this key, then click Create.
4

Copy and store the key

Copy the key immediately — it is shown only once. Store it in a secrets manager (such as AWS Secrets Manager, HashiCorp Vault, or Azure Key Vault) or in an environment variable in your deployment environment.
export ORKESTA_API_KEY="your_api_key_here"

​
Key scopes

Each API key is assigned one of three scopes that determine what it can access.
ScopeDescription
read-onlyCan retrieve data (accounts, payments, reports) but cannot create, update, or delete any resources. Use for dashboards and read-only integrations.
read-writeCan read and write all payment and integration resources. Suitable for most server-side integrations, including creating payments and configuring webhooks.
adminFull access, including workspace settings, user management, and API key management. Restrict this scope to internal tooling only.

​
Rotating API keys

Rotate keys periodically or immediately if you suspect a key has been compromised.
1

Generate a new key

Follow the steps in Generating an API key to create a replacement key with the same scope.
2

Update your integration

Deploy the new key to all services that use the old one. Update your environment variables or secrets manager entries before proceeding.
3

Verify the new key works

Make a test request using the new key — for example, GET /accounts — and confirm you receive a 200 response.
4

Revoke the old key

In Settings → API Keys, find the old key and click Revoke. The key is invalidated immediately. Any requests still using it will receive a 401 error.
There is a brief period during rotation when two keys are active simultaneously. If you revoke the old key before all your services are updated, those services will start returning 401 errors. Complete step 2 fully before revoking.

​
Error responses

The following HTTP status codes indicate authentication or authorization problems.
Status codeErrorCause
401 UnauthorizedMissing or invalid API keyThe Authorization header is absent, malformed, or the key does not exist or has been revoked.
403 ForbiddenInsufficient scopeThe key is valid, but its scope does not permit the requested action. Use a key with a higher scope.
429 Too Many RequestsRate limit exceededYour key has exceeded the allowed request rate. Back off and retry after the interval indicated in the Retry-After response header.