Skip to main content

Authentication API

Manage integrations and create Vault sessions for authorizing SaaS platforms.

GET /auth/integrations​

List all supported integrations.

Request​

GET /auth/integrations

Headers:

  • X-API-KEY: Your internal API key
  • X-Tenant-Id: Tenant identifier

Response​

200 OK

{
  "success": true,
  "data": {
    "integrations": [
      {
        "id": "jira",
        "name": "JIRA",
        "unifiedApi": "issue-tracking",
        "description": "Atlassian JIRA issue tracking"
      },
      {
        "id": "github",
        "name": "GitHub",
        "unifiedApi": "issue-tracking",
        "description": "GitHub repositories and issues"
      },
      {
        "id": "salesforce",
        "name": "Salesforce",
        "unifiedApi": "crm",
        "description": "Salesforce CRM"
      },
      {
        "id": "microsoft-teams",
        "name": "Microsoft Teams",
        "unifiedApi": "messaging",
        "description": "Microsoft Teams messaging"
      },
      {
        "id": "notion",
        "name": "Notion",
        "unifiedApi": "file-storage",
        "description": "Notion workspace"
      },
      {
        "id": "outlook-calendar",
        "name": "Outlook Calendar",
        "unifiedApi": "calendar",
        "description": "Microsoft Outlook Calendar"
      }
    ]
  },
  "meta": {
    "tenantId": "my-tenant",
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

Example​

curl http://localhost:3007/auth/integrations \
  -H "X-API-KEY: your-internal-key" \
  -H "X-Tenant-Id: my-tenant"

POST /auth/vault-session​

Create an Apideck Vault session for authorizing an integration.

Request​

POST /auth/vault-session
Content-Type: application/json

Headers:

  • X-API-KEY: Your internal API key
  • X-Tenant-Id: Tenant identifier

Body:

{
  "integration": "jira",
  "redirectUri": "https://myapp.com/callback",
  "vaultName": "Connect Your Account",
  "primaryColor": "#0052CC"
}

Request Parameters​

ParameterTypeRequiredDescription
integrationstringNoPredefined integration ID (jira, github, salesforce, microsoft-teams, notion)
unifiedApisarrayNoCustom unified APIs (e.g., ["crm", "messaging"])
redirectUristringNoURL to redirect after authorization
vaultNamestringNoCustom name for the vault UI
primaryColorstringNoCustom primary color (hex)

Note: Either integration or unifiedApis should be provided. If neither is provided, all integrations will be shown.

Response​

201 Created

{
  "success": true,
  "data": {
    "sessionUri": "https://vault.apideck.com/session/abc123",
    "consumerId": "consumer-123"
  },
  "meta": {
    "tenantId": "my-tenant",
    "integration": "jira",
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

Response Fields​

FieldTypeDescription
sessionUristringURL to redirect user for OAuth authorization
consumerIdstringApideck consumer ID for the tenant

Examples​

Authorize JIRA​

curl -X POST http://localhost:3007/auth/vault-session \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your-internal-key" \
  -H "X-Tenant-Id: my-tenant" \
  -d '{
    "integration": "jira"
  }'

Authorize Salesforce​

curl -X POST http://localhost:3007/auth/vault-session \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your-internal-key" \
  -H "X-Tenant-Id: my-tenant" \
  -d '{
    "integration": "salesforce",
    "redirectUri": "https://myapp.com/callback"
  }'

Authorize Multiple Unified APIs​

curl -X POST http://localhost:3007/auth/vault-session \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your-internal-key" \
  -H "X-Tenant-Id: my-tenant" \
  -d '{
    "unifiedApis": ["crm", "messaging"],
    "vaultName": "Connect CRM & Messaging"
  }'

Show All Integrations​

curl -X POST http://localhost:3007/auth/vault-session \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your-internal-key" \
  -H "X-Tenant-Id: my-tenant" \
  -d '{}'

Authorization Flow​

  1. Create Vault Session: Call this endpoint to get a sessionUri
  2. Redirect User: Redirect the user to the sessionUri
  3. User Authorizes: User completes OAuth flow in Apideck Vault
  4. Callback: User is redirected to your redirectUri (if provided)
  5. Use Integration: Integration is now authorized and ready to use

Error Responses​

400 Bad Request - Invalid integration name

{
  "success": false,
  "error": {
    "code": "INVALID_INTEGRATION",
    "message": "Integration 'invalid' is not supported"
  }
}

401 Unauthorized - Missing API key

403 Forbidden - Invalid API key

404 Not Found - Tenant not found

429 Too Many Requests - Rate limit exceeded

Rate Limiting​

This endpoint is rate-limited to 10 requests per 15 minutes per IP address.