Skip to main content
Standalone API Keys provide a simple way to authenticate requests to Pleo APIs using a company-controlled credential instead of delegated user authorisation. A Standalone API Key is generated directly from the Pleo Web App and allows systems to access Pleo APIs for a single organisation, without requiring an OAuth 2.0 authorisation flow. Standalone API Keys are primarily intended for API exploration, internal tooling, and Pleo pre-approved single-company integrations. For most production integrations, especially those connecting multiple customers, OAuth 2.0 remains the recommended authorisation method.

​
Concepts and Terminology

Before getting started, it helps to understand how Standalone API Keys are used within the Pleo platform.
ConceptTermDescription
Company credentialStandalone API KeyA secret key generated in the Pleo Web App used to authenticate API requests for a single company.
EnvironmentStaging / ProductionThe Pleo environment where the API Key is created and valid. Keys only work in the environment where they were generated.
Permission boundaryAPI scopesPermissions assigned to a key that define which API actions it may perform.
Company identityCompany_idThe Pleo company identity whose data the API Key can access.
Unlike OAuth 2.0, Standalone API Keys do not represent a user or external application acting on behalf of multiple customers. Instead, they represent direct access granted by a company to its own systems.

​
When to Use Standalone API Keys

Standalone API Keys are appropriate when API access is limited to a single organisation and user authorisation is not required. Typical use cases include:
  • Exploring or testing Pleo APIs during development
  • Building internal tools or scripts
  • Exporting data to internal systems or data warehouses
  • One-off migrations or reporting workflows
  • Approved integrations that cannot support OAuth 2.0 or Integrated API Keys (for example, legacy systems or restricted environments)

​
When to Use OAuth 2.0 Instead

OAuth 2.0 should be used if your integration:
  • Connects multiple Pleo customers
  • Acts on behalf of users or external organisations
  • Requires customer consent and revocable access
  • Will be distributed as a partner or marketplace integration
OAuth 2.0 provides delegated, user-authorised access and is the default authentication method for most integrations. See the OAuth 2.0 Overview for details.

​
How Standalone API Keys Work (Conceptually)

​
Environment-Scoped Access

Each Standalone API Key is bound to the environment where it was created:
  • A key created in Staging only works in Staging
  • A key created in Production only works in Production
Keys cannot be reused across environments.

​
Permission-Scoped Access

When creating a key, you select API scopes that define allowed actions. For example:
  • users:read
  • export-jobs:read
  • export-jobs:write
The key can only perform operations allowed by its assigned scopes.

​
Company-Scoped Authentication

Standalone API Keys provide access to a single Pleo company. API requests must include the correct company_id, ensuring requests operate within the intended organisational boundary. This results in a 1-to-1 integration model between a system and a Pleo organisation. The same principle applies to multi-entity accounts. Detailed guidance on API scopes, company scoping, and integration lifecycle is in Integration Design for Standalone API Keys.

​
Security Responsibilities (High-Level)

Because Standalone API Keys act as secret credentials, your organisation is responsible for protecting them:
  • Store API Keys securely and never expose them publicly
  • Avoid embedding keys in client-side applications
  • Use the minimum required API scopes
  • Rotate or replace keys if compromised
For implementation best practices and lifecycle handling, see Security and Credential Management for Standalone API Keys.

​
Standalone API Keys vs OAuth 2.0

Standalone API KeysOAuth 2.0
AvailabilityRestrictedAvailable
Access modelCompany-controlledUser-delegated
Typical usageInternal or exploratoryCustomer integrations
Customer consentNot requiredRequired
Multi-customer supportNoYes
AuthenticationStatic API keyAccess tokens
Recommended for production integrationsLimited casesYes

​
Typical Development Workflow

  1. Explore APIs using Standalone API Keys
  2. Prototype workflows and validate API usage
  3. Implement Standalone API Keys for production integrations (where approved by Pleo)
  4. Implement OAuth 2.0 for production integrations (recommended)
Implementation details for installation, activation, key updates, and error handling are covered in:

​
What Comes Next?

​
FAQs

Legacy APIs (OpenAPI)
  • Base URL: https://openapi.pleo.io
  • Authentication: API tokens (legacy tokens)
  • Availability: Intended for existing/legacy use cases. Access can depend on your account setup and entitlements.
  • Lifecycle: Deprecated. Pleo is working on a deprecation timeline and migration plan.
New APIs (External API)
  • Base URL: https://external.pleo.io
  • Authentication: API keys (and other authentication methods supported by the platform, including OAuth 2.0, depending on the use case)
  • Availability: Restricted access. Documentation may be publicly visible, but access is not broadly enabled by default. Standalone API keys require explicit enablement.
  • What to expect: Newer platform surface and improved structure, but not guaranteed feature parity with legacy APIs yet.
Important:
  • Legacy API tokens will not work on external.pleo.io
  • New API keys will not work on openapi.pleo.io
For more context on Standalone API Keys and environment restrictions, see the Standalone API Keys Overview article.