Authentication

Learn how to authenticate your API requests using API keys and bearer tokens.

All Stepsies API requests require authentication using an API key. This guide explains how to create, manage, and use API keys.

Overview

The Stepsies API uses Bearer token authentication. Include your API key in the Authorization header of every request:

Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keep your API keys secure

Never expose API keys in client-side code, public repositories, or version control. Store them in environment variables or a secrets manager.

Creating an API Key

  1. Go to your Dashboard and click on the Developer tab
  2. Click Create API Key
  3. Give your key a descriptive name (e.g., “Production Backend”, “CI/CD Pipeline”)
  4. Select the scopes your application needs
  5. Optionally set an expiration date
  6. Click Create Key

One-time display

Your API key is only shown once when created. Copy it immediately and store it securely. If you lose it, you’ll need to create a new key.

API Key Format

All Stepsies API keys follow this format:

sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  • Prefix: sk_ identifies it as a Stepsies API key
  • Token: 48 random hexadecimal characters
  • Total length: 51 characters

Scopes

API keys can have one or more scopes that limit what actions they can perform:

Scope Description Use Case
read Read-only access to your stepsies and profile Analytics dashboards, public displays
write Create, update, and delete stepsies Content management, automation
admin Full access including user management Administrative tools, migrations

Scope hierarchy

The admin scope includes all permissions from read and write scopes.

Scope Requirements by Endpoint

Endpoint Required Scope
GET /stepsies read
GET /stepsies/:id read
POST /stepsies write
PATCH /stepsies/:id write
DELETE /stepsies/:id write
POST /stepsies/:id/publish write
POST /stepsies/:id/unpublish write

Making Authenticated Requests

Using cURL

curl https://api.stepsies.com/v1/stepsies \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -H "Content-Type: application/json"

Using JavaScript (fetch)

const response = await fetch('https://api.stepsies.com/v1/stepsies', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer sk_your_api_key_here',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();

Using Ruby

require 'net/http'
require 'json'

uri = URI('https://api.stepsies.com/v1/stepsies')
request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer sk_your_api_key_here'
request['Content-Type'] = 'application/json'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)

Using Python

import requests

response = requests.get(
    'https://api.stepsies.com/v1/stepsies',
    headers={
        'Authorization': 'Bearer sk_your_api_key_here',
        'Content-Type': 'application/json'
    }
)

data = response.json()

Authentication Errors

401 Unauthorized

Returned when no API key is provided or the key is invalid:

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key"
  }
}

Common causes: - Missing Authorization header - Typo in the API key - Using a revoked key - Using an expired key

403 Forbidden

Returned when your API key doesn’t have the required scope:

{
  "error": {
    "code": "forbidden",
    "message": "Insufficient scope for this action"
  }
}

Solution: Create a new API key with the required scope, or upgrade your existing key.

Managing API Keys

Viewing Keys

Go to Dashboard > Developer to see all your API keys. For each key, you can see:

  • Name and description
  • Scopes granted
  • Creation date
  • Last used timestamp
  • Expiration date (if set)

Revoking Keys

If you suspect a key has been compromised, revoke it immediately:

  1. Go to Dashboard > Developer
  2. Find the key you want to revoke
  3. Click the Revoke button
  4. Confirm the action

Revoked keys stop working immediately. Any requests using a revoked key will receive a 401 Unauthorized error.

Revocation is immediate and permanent

Once a key is revoked, it cannot be reinstated. You’ll need to create a new key and update your integrations.

Best Practices

  1. Use descriptive names — Name keys by their purpose (“Zapier Integration”, “Mobile App”, “CI Pipeline”)

  2. Principle of least privilege — Only grant the scopes your application actually needs

  3. Set expiration dates — For temporary integrations, set keys to expire automatically

  4. Rotate keys regularly — Create new keys and retire old ones periodically

  5. Monitor usage — Check the “last used” timestamp to identify unused keys

  6. Use environment variables — Store keys in STEPSIES_API_KEY environment variable

  7. One key per integration — Use separate keys for different applications to isolate access

Next Steps

On this page