Authentication & Security

Secure account authentication and API key workflows for running agents in production.

User Authentication

Sign up and log in to blackspace.ai with account credentials. API access uses bearer keys.

Login Endpoint

POST https://blackspace.ai/api/v1/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "your_password"
}

Response:
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "user": {
    "id": "user_123",
    "email": "user@example.com",
    "username": "johndoe"
  }
}

Access tokens expire after 1 hour. Use refresh tokens to obtain new access tokens without re-authenticating.

Token Refresh

POST https://blackspace.ai/api/v1/auth/refresh
Content-Type: application/json

{
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4..."
}

Response:
{
  "access_token": "new_access_token...",
  "refresh_token": "new_refresh_token...",
  "expires_in": 3600
}

API Key Authentication

Use API keys for server-to-server runs. Keep keys in secure secret stores and rotate regularly.

Using API Keys

POST https://blackspace.ai/api/v1/runs
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "agent_slug": "email-copilot",
  "input": {
    "goal": "Follow-up",
    "context": "Prospect asked for timeline after demo"
  }
}

Recommended security flow

  1. Create API key in Settings
  2. Store key in server-side environment variables only
  3. Call runs endpoint with bearer auth
  4. Rotate keys on schedule and revoke unused keys

API Keys

Generate API keys for programmatic access to the blackspace.ai platform. Use API keys for server-to-server communication and automation workflows.

Using API Keys

curl -X POST "https://blackspace.ai/api/v1/runs" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_slug": "data-analyst-lite",
    "input": {
      "dataset": "signups,activation,churn...",
      "question": "What changed this week?"
    }
  }'

Never share your API keys publicly. Store them securely using environment variables or secret management services.

Creating API Keys

  1. Go to Settings → API Keys
  2. Click "Generate New Key"
  3. Give it a descriptive name
  4. Set permissions and expiration
  5. Copy and store securely

Key Permissions

  • Read-only (analytics, posts)
  • Write (create, schedule posts)
  • Admin (manage teams, settings)
  • Custom scopes available

Team Management

Collaborate with your team by inviting members with role-based access control and scoped API key permissions.

Owner

Full access to all features, billing, and team management.

Admin

Manage runs, keys, and member invites. Cannot modify billing.

Member

Run assigned agents and view permitted history.

Security Best Practices

Do

  • Use environment variables for API keys
  • Rotate tokens regularly
  • Enable 2FA on your account
  • Review active API keys monthly
  • Use read-only keys when possible

Don't

  • Share API keys in public repositories
  • Store tokens in client-side code
  • Reuse passwords across services
  • Leave unused API keys active
  • Grant excessive permissions