Skip to main content

Authentication

Inttegro authenticates API requests with an opaque bearer key. Keep the key in server-side secret storage and include it in the Authorization header for every request.

Prerequisites

  • An Inttegro application
  • An API key generated from the dashboard
  • A server-side runtime that can read secrets from its environment

Send the bearer header

Set the header value to Bearer followed by the complete opaque key:

Authorization: Bearer <SECRET_KEY_TOKEN>

Do not parse the token, infer an environment from its characters, embed it in browser or mobile code, commit it to source control, or log it. A missing, malformed, or invalid credential returns 401 Unauthorized.

Make an authenticated request

This example creates a finalized order through the official SDKs. The raw HTTP response uses an { "order": { ... } } envelope; the SDKs return the order domain object directly.

Authenticated request

POST/orders/create
response=$(curl https://api.inttegro.com/orders/create \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: auth-example-order-123" \
  -d '{
    "finalize": true,
    "customer_data": {
      "name": "Akua Mensah",
      "email_address": "[email protected]",
      "phone_number": "+233544998605"
    },
    "line_items": [{
      "product": {
        "name": "Premium Subscription",
        "price": { "currency": "ghs", "value": 5000 },
        "quantity": 1,
        "type": "service"
      },
      "type": "product"
    }]
  }')

invoice_url=$(jq -er '.order.invoice.format.web.url' <<< "$response")

Store credentials safely

Load the Inttegro key only in server-side code. Your process can still read INTTEGRO_API_KEY from the environment at runtime; the important part is that the value is injected from a protected secret system, not committed to source control, copied into a public client bundle, or shared in plaintext.

Environment variable
INTTEGRO_API_KEY=<SECRET_KEY_TOKEN>

Choose the source of truth based on how your team ships software. If the key is used by more than one service, deploy pipeline, or developer environment, keep it in a dedicated secret store instead of maintaining separate .env files by hand:

  • Doppler or Infisical work well when you want one application-focused source of truth across local development, CI, and deployments.
  • 1Password Environments is a good fit when developer credentials already live in 1Password and local commands should receive secrets without writing plaintext .env files.
  • Use AWS Secrets Manager, Google Cloud Secret Manager, or Azure Key Vault when your application already runs in one of those clouds and can use its IAM or workload identity model.
  • HashiCorp Vault makes sense when your infrastructure team already operates Vault or needs centralized policy, dynamic credentials, and explicit lease management.

At the deployment boundary, prefer the secret feature provided by your host. These platforms commonly expose the value to your application as an environment variable, but store and protect it differently from ordinary configuration:

Use separate credentials for development, staging, and production, and restrict access to the deployment identities that actually make Inttegro requests. Avoid client-exposed prefixes such as NEXT_PUBLIC_, VITE_, or EXPO_PUBLIC_; an Inttegro API key must only be loaded by server-side code. If a key may have been disclosed, generate a replacement, deploy it, verify requests with the new credential, and retire the old key.

Handle authentication failures

A 401 Unauthorized response means Inttegro could not authenticate the request. Verify that the header uses the exact Bearer <token> format, the complete token was loaded, and the credential is still active. Do not print the key while diagnosing the failure.

Authentication proves which application made the request. It does not by itself prove a customer's identity or authorize a payment; keep those decisions in the corresponding checkout or verification flow.