Create and manage API keys for programmatic access to Stamp0. Use in CI pipelines, tests, and applications.

API keys let you interact with Stamp0 programmatically from your tests, CI pipelines, or applications.

Creating an API Key

Navigate to API Keys

Go to Organization Settings → API Keys

Create Key

Click Create API Key
Enter a descriptive name (e.g., "CI Pipeline" or "E2E Tests")
Select which projects this key can access:
- All Projects: Key can access all current and future projects
- Specific Projects: Key can only access selected projects
Optionally set an expiration date
Click Create

Copy Key

Important: Copy your API key immediately. It's only shown once and cannot be retrieved later.

sk_live_abc123...

Security Warning: API keys grant access to your Stamp0 resources. Keep them secure and never commit them to version control.

API Key Format

API keys follow this format:

sk_live_[random string]

Example: sk_live_abc123def456ghi789

Using API Keys

In Environment Variables

Store your API key securely:

# .env file (add to .gitignore!)
STAMP0_API_KEY=sk_live_your_key_here

With the SDK

import { Stamp0 } from '@stamp0/sdk';

const stamp0 = new Stamp0({
  apiKey: process.env.STAMP0_API_KEY,
});

const inbox = await stamp0.createInbox({
  projectId: 'prj_abc123',
});

With cURL

curl -X POST https://api.stamp0.com/v1/inboxes \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"projectId": "prj_abc123"}'

In CI Pipelines

GitHub Actions

# .github/workflows/e2e.yml
name: E2E Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run tests
        run: npm test
        env:
          STAMP0_API_KEY: ${{ secrets.STAMP0_API_KEY }}
          STAMP0_PROJECT_ID: ${{ secrets.STAMP0_PROJECT_ID }}

Add secrets in GitHub: Settings → Secrets and variables → Actions

GitLab CI

# .gitlab-ci.yml
test:
  script:
    - npm test
  variables:
    STAMP0_API_KEY: $STAMP0_API_KEY
    STAMP0_PROJECT_ID: $STAMP0_PROJECT_ID

Add variables in GitLab: Settings → CI/CD → Variables

CircleCI

# .circleci/config.yml
jobs:
  test:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - run:
          name: Run tests
          command: npm test
          environment:
            STAMP0_API_KEY: ${STAMP0_API_KEY}

Add environment variables in CircleCI project settings.

Managing API Keys

Viewing Keys

Go to Organization Settings → API Keys to see:

Column	Description
Name	Descriptive name
Key Prefix	First few characters (for identification)
Projects	Which projects the key can access
Created	When the key was created
Expires	Expiration date (if set)
Actions	Edit, disable, delete

Editing Keys

You can edit:

Key name
Project access

You cannot:

View the full key after creation
Change the key value

Disabling Keys

Temporarily disable a key without deleting it:

Find the key in the list
Toggle the Enabled switch to off

Disabled keys will return 401 Unauthorized errors.

Deleting Keys

To permanently delete a key:

Click the delete icon
Confirm deletion

Deleting a key is permanent. Any systems using the key will immediately lose access.

Project Scoping

All Projects Access

Keys with "All Projects" access can:

Create inboxes in any project
Access emails in any project
Work with future projects automatically

Use for: CI pipelines that test across multiple projects

Specific Project Access

Keys scoped to specific projects can only:

Create inboxes in those projects
Access emails in those projects

Use for: Limited access, third-party integrations

// This will fail if key doesn't have access to prj_xyz
const inbox = await stamp0.createInbox({
  projectId: 'prj_xyz', // Key must have access to this project
});

Rate Limits

API keys have rate limits to prevent abuse:

Limit	Value
Default	100 requests per 24 hours
Custom	Can be increased on request

When you exceed the limit:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 3600 seconds."
  }
}

Response includes:

429 Too Many Requests status code
Retry-After header with seconds until reset

Handling Rate Limits

try {
  const inbox = await stamp0.createInbox({ projectId });
} catch (error) {
  if (error.code === 'rate_limit_exceeded') {
    console.log('Rate limited, waiting...');
    await new Promise(r => setTimeout(r, error.retryAfter * 1000));
    // Retry
  }
}

Security Best Practices

API Key Security:

Never commit keys to version control
Use environment variables for all key storage
Rotate keys periodically (every 90 days recommended)
Use scoped keys when possible (specific projects vs all)
Delete unused keys promptly
Use separate keys for different environments (dev, staging, prod)

Key Rotation

To rotate a key:

Create a new key with the same permissions
Update your systems to use the new key
Verify everything works
Delete the old key

Least Privilege

Create keys with minimal necessary access:

❌ Bad: One "master" key used everywhere

✅ Good:
├── "CI Pipeline" - All projects (for automated tests)
├── "Local Dev" - Development project only
└── "Staging" - Staging project only