Authentication

How to authenticate Sporeline API requests with an API key, and what a key can access.

developer

Authentication

Every request to the Sporeline API must carry credentials in the Authorization header. The API accepts two schemes:

SchemeHeaderUse it for
API keyAuthorization: ApiKey <key>Your scripts and integrations
Cognito ID tokenAuthorization: Bearer <token>The Sporeline web and mobile apps

For anything you build, use an API key.

All requests go to:

https://9uvbgolte1.execute-api.us-east-1.amazonaws.com/prod

Getting an API Key

A Manager or Owner creates keys under Settings > API Keys. See API Keys for the steps.

  • A key looks like mt_live_ followed by 32 characters.
  • The full key is shown once, when you create it. Sporeline keeps only a hash of it, so it can’t show the key again.
  • An account can have up to 10 active keys.
  • A key never expires unless you give it an expiration date.

Sending the Key

Put the key in the Authorization header, after the word ApiKey and a space:

curl -H "Authorization: ApiKey $SPORELINE_API_KEY" \
  https://9uvbgolte1.execute-api.us-east-1.amazonaws.com/prod/recipes

The scheme matters. Sending an API key as Bearer <key> fails with 401, because Bearer is reserved for Cognito tokens.

What a Key Can Access

Your account only. A key belongs to the account that created it, and every request made with it is scoped to that account’s data. You never pass an account or tenant ID.

The Manager role. Requests made with an API key run with the Manager role, and a key can do most of what a Manager can in the app. Some things need a person signed in to Sporeline and return 403 to a key: changing settings, setting up integrations (QuickBooks, Shopify, webhooks, sensors), importing config, editing notification templates, and creating or revoking API keys. Actions that need the Owner role return 403 too.

Revoking a Key

Revoke a key from Settings > API Keys. Revoked keys can’t be turned back on.

A revoked key stops working within five minutes. The API remembers a successful authorization for up to five minutes, so a key that was in use just before you revoked it can keep working briefly. The same applies when a key reaches its expiration date.

To rotate a key without downtime, create the new key, switch your integration to it, then revoke the old one.

When Authentication Fails

If the header is missing or malformed, or the key is unknown, revoked or expired, the API returns 401:

{
  "error": {
    "code": "SESSION_EXPIRED",
    "message": "Your session has expired. Please sign in again.",
    "retry": false
  }
}

The message is written for people using the Sporeline app, and it’s the same whatever the cause. For an integration, it means the key wasn’t accepted. Check that the header uses the ApiKey scheme and that the key is still active.

If the key is valid but its role isn’t allowed to perform the action, the API returns 403 with the code FORBIDDEN. See Error Codes.

Cognito Tokens

The Sporeline apps sign users in with Amazon Cognito and send the user’s ID token as Bearer <token>. These requests run with the signed-in user’s own role. ID tokens expire after one hour, which is why integrations should use API keys instead.

Related Pages