Authentication

All API requests require authentication using Bearer tokens. Include your API key in the Authorization header of each request. API keys are scoped to your shop and should be kept secure—treat them like passwords and never expose them in client-side code or public repositories.

Bearer token authentication

The PostCo API uses Bearer token authentication. Every request must include your API key in the Authorization header using this format:

Example request with Bearer token

curl https://360.postco.co/api/public/v1/return_orders \
  -H "Authorization: Bearer sk_your_api_key_here"

The API key must be prefixed with Bearer (note the space after "Bearer").

Generating API keys

You can generate and manage API keys from your PostCo retailer dashboard:

  1. Log in to 360.postco.co
  2. In the bottom left corner of the sidebar, click the Account Settings icon (it looks like a grid/template icon), then select Manage API Keys
  3. Click Create API Key
  4. Provide a descriptive name (e.g., "Production Server" or "Analytics Integration")
  5. Copy the key immediately—it will only be shown once

Once created, you'll receive an API key in this format:

sk_a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdefabcd

API key characteristics

  • Prefix: All API keys start with sk_ (secret key)
  • Length: 67 characters total (3-character prefix + 64 hexadecimal characters)
  • Entropy: 256 bits of cryptographic randomness
  • Scope: Each key is tied to a single shop and can only access that shop's data
  • Visibility: The full key is only displayed once at creation

Security best practices

  • Name
    Store securely
    Description

    Use environment variables or a secrets management system. Never hardcode API keys in your application code.

  • Name
    Never commit to version control
    Description

    Add API keys to your .gitignore file. Accidentally committed keys should be revoked immediately.

  • Name
    Rotate regularly
    Description

    Create a new API key every 90 days. Generate the new key, update your integration, then revoke the old key.

  • Name
    Use descriptive names
    Description

    Name keys by their purpose or integration (e.g., "Warehouse Management System" or "BI Tool"). This helps track usage and identify which integration is affected if a key needs to be revoked.

  • Name
    Revoke unused keys
    Description

    Check the last_used_at timestamp in the dashboard. Revoke keys that haven't been used in over 90 days to reduce your attack surface.

Multi-tenant isolation

Each API key is scoped to a specific shop. This means:

  • You can only access data belonging to your shop
  • Cross-tenant data access is impossible
  • Even with a valid API key, you cannot view or modify another shop's return orders

This ensures complete data isolation in our multi-tenant environment.

Revoking API keys

If an API key is compromised or no longer needed:

  1. In your dashboard, click the Account Settings icon (bottom left of the sidebar) » Manage API Keys
  2. Find the key in the list (identified by its last 4 characters)
  3. Click Revoke

Revoked keys are immediately invalidated. Any requests using a revoked key will receive a 401 Unauthorized response.

Troubleshooting authentication

  • Name
    401 Unauthorized: Missing API key
    Description

    The request is missing the Authorization header or the header doesn't start with Bearer .

  • Name
    401 Unauthorized: Invalid or revoked API key
    Description

    The API key is incorrect, doesn't start with sk_, has been revoked, or doesn't exist in the system.

  • Name
    404 Not Found
    Description

    Authentication succeeded, but the requested resource doesn't exist or doesn't belong to your shop.

If you're still having issues, verify:

  • The API key is copied correctly (67 characters, starts with sk_)
  • The Authorization header format is: Authorization: Bearer sk_...
  • The key hasn't been revoked in the dashboard
  • You're making requests to https://360.postco.co/api/public/v1/...

Was this page helpful?