AllSign

Authentication

You'll need to authenticate your requests to access any of the endpoints in the AllSign API. AllSign uses Bearer token authentication with API keys that include scope-based permissions, IP allowlists, and rate limiting.

API Key Format

AllSign API keys follow a structured format that identifies the environment, key type, and includes a secure random token:

allsign_{environment}_{type}_{random}
  • Name
    environment
    Description
    • live: Production environment
    • test: Testing/development environment
  • Name
    type
    Description
    • sk: Secret Key (server-side use only)
    • user_sk: User-specific Secret Key
  • Name
    random
    Description

    Cryptographically secure random string for uniqueness

Example Keys

# Production API Key
allsign_live_sk_abc123xyz789...

# Test Environment Key
allsign_test_sk_def456uvw012...

# User-specific Key
allsign_live_user_sk_ghi789rst345...

Never commit API keys to version control. Use environment variables or secret management tools to store your keys securely.

Bearer Token Authentication

All API requests must include your API key in the Authorization header using the Bearer token scheme:

Add your API key to the Authorization header prefixed with Bearer. This is the only supported authentication method for the AllSign API.

cURL Example

curl https://api.allsign.io/v2/documents \
  -H "Authorization: Bearer allsign_live_sk_abc123xyz789"

JavaScript Example

const response = await fetch('https://api.allsign.io/v2/documents', {
  headers: {
    'Authorization': 'Bearer allsign_live_sk_abc123xyz789',
    'Content-Type': 'application/json'
  }
});

Python Example

import requests

headers = {
    'Authorization': 'Bearer allsign_live_sk_abc123xyz789',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.allsign.io/v2/documents',
    headers=headers
)

Dual-Mode Authentication

AllSign supports two authentication modes to accommodate different use cases:

Mode 1: User-Specific API Key

Use a user-specific API key that directly identifies the user making the request. This is the simplest approach for single-user applications.

User API Key

curl https://api.allsign.io/v2/documents \
  -H "Authorization: Bearer allsign_live_user_sk_abc123"

Mode 2: App API Key + X-User-Id

For multi-user applications (like integrations or platforms), use an app-level API key combined with the X-User-Id header to specify which user's context to operate in.

This pattern enables:

  • Building multi-tenant applications
  • Cross-tenant collaboration via permissions
  • Centralized API key management

App API Key + X-User-Id

curl https://api.allsign.io/v2/documents \
  -H "Authorization: Bearer allsign_live_sk_xyz789" \
  -H "X-User-Id: 550e8400-e29b-41d4-a716-446655440000"

Multi-user App Example

const response = await fetch('https://api.allsign.io/v2/documents', {
  headers: {
    'Authorization': 'Bearer allsign_live_sk_xyz789',
    'X-User-Id': '550e8400-e29b-41d4-a716-446655440000',
    'Content-Type': 'application/json'
  }
});

Mode 3: Delegated Access

Use delegated access when your team needs to take an action on behalf of a specific customer (for example, a support teammate sending a document for a member). Your platform keeps using its App API Key, but you include the X-On-Behalf-Of header so AllSign knows which end user should appear as the actor.

How to send delegated requests

  1. Use an App API Key (server-to-server credential).
  2. Add X-On-Behalf-Of with the identifier you use to reference the end user (email or user ID).
  3. Send the request as usual; AllSign will execute the action for that person while still logging your platform as the initiator.

Why teams use it

  • Support tooling can fix or resend items without asking customers for their API keys.
  • Audit logs clearly show both the platform account and the end user who benefited.
  • You can keep a consistent experience for customers while automating behind the scenes.

Delegated Access Request

curl https://api.allsign.io/v2/documents \
  -H "Authorization: Bearer allsign_live_sk_xyz789" \
  -H "X-On-Behalf-Of: member@example.com"

Request Metadata Logged

{
  "apiKeyOwner": "platform@app.com",
  "onBehalfOf": "member@example.com",
  "scopes": ["document:read", "document:write"],
  "mode": "delegated"
}

Scopes & Permissions

AllSign API keys include granular scope-based permissions that control what operations can be performed:

Document Scopes

  • document:read - List and view documents
  • document:write - Create and update documents
  • document:delete - Delete documents
  • document:* - All document operations

Signature Scopes

  • signature:read - View signatures
  • signature:write - Create and update signatures
  • signature:* - All signature operations

API Key Metadata Example

{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_email": "user@example.com",
  "tenant_id": "tenant_abc123",
  "scopes": [
    "document:read",
    "document:write",
    "signature:read"
  ],
  "environment": "live",
  "rate_limit_config": {
    "requests_per_minute": 60,
    "requests_per_hour": 1000
  }
}

Insufficient Permissions

If your API key lacks the required scope, you'll receive a 403 Forbidden response:

403 Forbidden Response

{
  "detail": "Insufficient permissions. Required: document:write or document:*. Your scopes: document:read, signature:read"
}

Security Features

IP Allowlists

Restrict API key usage to specific IP addresses or CIDR ranges. When configured, requests from unauthorized IPs are automatically rejected.

Supported formats:

  • Single IP: 203.0.113.42
  • CIDR range: 10.0.0.0/16

IP Allowlist Configuration

{
  "allowed_ips": [
    "203.0.113.42",
    "198.51.100.0/24",
    "192.0.2.1"
  ]
}

403 IP Blocked Response

{
  "detail": "Access from this IP is not allowed for this API key"
}

Rate Limiting

API keys include rate limit configurations to prevent abuse:

  • Name
    requests_per_minute
    Type
    integer
    Description

    Maximum requests allowed per minute (default: 60)

  • Name
    requests_per_hour
    Type
    integer
    Description

    Maximum requests allowed per hour (default: 1000)

When rate limits are exceeded, you'll receive a 429 Too Many Requests response with retry information in the headers.

Environment Isolation

API keys are environment-specific:

  • live keys only work with production data
  • test keys only work with test data

This prevents accidental mixing of production and test data.

Error Responses

401 Unauthorized

Missing Authorization Header

{
  "detail": "Missing Authorization header. Use: Authorization: Bearer allsign_live_sk_xxx"
}

Invalid API Key Format

{
  "detail": "Invalid API key format. Expected: allsign_{env}_{type}_{random}"
}

Invalid or Expired Key

{
  "detail": "Invalid or expired API key"
}

403 Forbidden

Insufficient Scopes

{
  "detail": "Insufficient permissions. Requires ANY of these scopes: document:write, document:*. Your scopes: document:read"
}

Managing API Keys

You can create, view, and revoke API keys from the AllSign Dashboard:

  1. Navigate to Settings → API Keys
  2. Create New Key - Select scopes and optionally configure IP allowlists
  3. Copy Key - The full key is only shown once during creation
  4. Revoke Key - Immediately invalidate a compromised key

Store your API key securely immediately after creation. For security reasons, the full key cannot be retrieved later—only the last 4 characters are displayed in the dashboard.

Best Practices

  • Name
    Use environment variables
    Description

    Never hardcode API keys in your source code. Use environment variables or secret management services like AWS Secrets Manager, HashiCorp Vault, or your platform's secret store.

  • Name
    Principle of least privilege
    Description

    Create API keys with only the scopes required for their specific purpose. Use document:read for read-only operations instead of document:*.

  • Name
    Separate keys per environment
    Description

    Use different API keys for development, staging, and production environments. Never use production keys in development.

  • Name
    Rotate keys regularly
    Description

    Implement a key rotation schedule (e.g., every 90 days) to minimize the impact of potential compromises.

  • Name
    Monitor key usage
    Description

    Regularly review API usage logs to detect suspicious activity or unauthorized access patterns.

  • Name
    Use IP allowlists for servers
    Description

    When calling the API from servers with static IPs, configure IP allowlists to add an extra layer of security.

  • Name
    Revoke compromised keys immediately
    Description

    If you suspect a key has been compromised, revoke it immediately and generate a new one.

  • Name
    Prefer stable user identifiers
    Description

    For third-party integrators, treat the AllSign user_id (UUID) as the canonical actor identifier and use X-User-Id for the hot path.

    Why:

    • Emails are human-friendly but unstable: they can change, be normalized differently (case, dots, plus addressing), or even be recycled in some orgs.
    • Security is tighter with user_id: you avoid ambiguity, prevent email-enumeration attacks (different error messages), and keep authorization deterministic per tenant.
    • Performance scales better: resolving email → user_id requires lookups, normalization rules, and cache invalidation. UUIDs are constant-time keys.

    How to offer convenience without sacrificing rigor:

    • Accept X-On-Behalf-Email (or similar) as an onboarding aid so integrators can start from the identifier they already have.
    • Immediately exchange that email for the corresponding user_id, store it in your system, and switch to X-User-Id for subsequent calls.
    • Document clearly that email-based headers are a convenience layer, not the primary auth context, so your integration remains future-proof.

Was this page helpful?