SalesOS

A P I Keys

API key management

Get all API keys for current user

GET
/v1/api-keys

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

Query Parameters

statusstring
Value in: "ACTIVE" | "REVOKED" | "EXPIRED"
curl -X GET "https://api.salesos.org/v1/api-keys?status=ACTIVE" \
  -H "Authorization: Bearer <token>"

ApiKeyArray

[
  {
    "id": "string",
    "userId": "string",
    "organizationId": "string",
    "name": "string",
    "description": "string",
    "keyPrefix": "string",
    "scopes": [
      "string"
    ],
    "ipWhitelist": [
      "string"
    ],
    "domainWhitelist": [
      "string"
    ],
    "rateLimit": 0,
    "rateLimitWindow": 0,
    "status": "ACTIVE",
    "lastUsedAt": "2019-08-24T14:15:22Z",
    "usageCount": 0,
    "expiresAt": "2019-08-24T14:15:22Z",
    "rotatedFromId": "string",
    "rotatedAt": "2019-08-24T14:15:22Z",
    "revokedAt": "2019-08-24T14:15:22Z",
    "lastUsedIp": "string",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
]

Create a new API key

The secret is returned once. Keys are bound to the current organization.

POST
/v1/api-keys

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

Request Body

application/jsonRequired
nameRequiredstring

API key name

Maximum length: 120
descriptionstring

API key description

Maximum length: 500
scopesarray<string>

Scopes: READ_ / WRITE_ per resource (e.g. READ_LEADS), or * for everything. Items: at most 64.

Default: ["read"]
rateLimitnumber

Requests allowed per window

Default: 1000Minimum: 1Maximum: 1000000
rateLimitWindownumber

Rate limit window in seconds

Default: 3600Minimum: 1Maximum: 86400
allowedIpsarray<string>

IP allow-list: addresses or CIDR blocks (203.0.113.0/24, 2001:db8::/32). Empty allows any IP. Items: at most 100.

expiresAtstring

When the key stops working (ISO 8601). Omit for no expiry.

curl -X POST "https://api.salesos.org/v1/api-keys" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "description": "string",
    "scopes": [
      "READ_LEADS",
      "WRITE_CONTACTS"
    ],
    "rateLimit": 1000,
    "rateLimitWindow": 3600,
    "allowedIps": [
      "203.0.113.0/24"
    ],
    "expiresAt": "string"
  }'

ApiKeyCreated

{
  "id": "string",
  "name": "string",
  "key": "string",
  "keyPrefix": "string",
  "scopes": [
    "string"
  ],
  "rateLimit": 0,
  "rateLimitWindow": 0,
  "ipWhitelist": [
    "string"
  ],
  "expiresAt": "2019-08-24T14:15:22Z",
  "createdAt": "2019-08-24T14:15:22Z",
  "message": "string"
}

Get aggregate usage stats across all of current user's keys

GET
/v1/api-keys/usage

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

Query Parameters

dateFromstring
dateTostring
curl -X GET "https://api.salesos.org/v1/api-keys/usage?dateFrom=%3Cstring%3E&dateTo=%3Cstring%3E" \
  -H "Authorization: Bearer <token>"

Deprecated endpoints your organization's keys and sessions still call

GET
/v1/api-keys/deprecated-usage

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

Query Parameters

daysnumber
curl -X GET "https://api.salesos.org/v1/api-keys/deprecated-usage?days=0" \
  -H "Authorization: Bearer <token>"

Get an API key by ID

GET
/v1/api-keys/{id}

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

Path Parameters

idRequiredstring
curl -X GET "https://api.salesos.org/v1/api-keys/<string>" \
  -H "Authorization: Bearer <token>"

ApiKey

{
  "id": "string",
  "userId": "string",
  "organizationId": "string",
  "name": "string",
  "description": "string",
  "keyPrefix": "string",
  "scopes": [
    "string"
  ],
  "ipWhitelist": [
    "string"
  ],
  "domainWhitelist": [
    "string"
  ],
  "rateLimit": 0,
  "rateLimitWindow": 0,
  "status": "ACTIVE",
  "lastUsedAt": "2019-08-24T14:15:22Z",
  "usageCount": 0,
  "expiresAt": "2019-08-24T14:15:22Z",
  "rotatedFromId": "string",
  "rotatedAt": "2019-08-24T14:15:22Z",
  "revokedAt": "2019-08-24T14:15:22Z",
  "lastUsedIp": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Update an API key

PATCH
/v1/api-keys/{id}

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

Request Body

application/jsonRequired
namestring

API key name

Maximum length: 120
descriptionstring

API key description

Maximum length: 500
scopesarray<string>

Scopes/permissions for the key Items: at most 64.

rateLimitnumber

Requests allowed per window

Minimum: 1Maximum: 1000000
rateLimitWindownumber

Rate limit window in seconds

Minimum: 1Maximum: 86400
allowedIpsarray<string>

IP allow-list: addresses or CIDR blocks; [] allows any IP Items: at most 100.

expiresAtstring

Expiry (ISO 8601); null removes it

statusstring

API key status

Value in: "ACTIVE" | "REVOKED" | "EXPIRED"

Path Parameters

idRequiredstring
curl -X PATCH "https://api.salesos.org/v1/api-keys/<string>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "description": "string",
    "scopes": [
      "string"
    ],
    "rateLimit": 1,
    "rateLimitWindow": 1,
    "allowedIps": [
      "string"
    ],
    "expiresAt": "string",
    "status": "ACTIVE"
  }'

ApiKey

{
  "id": "string",
  "userId": "string",
  "organizationId": "string",
  "name": "string",
  "description": "string",
  "keyPrefix": "string",
  "scopes": [
    "string"
  ],
  "ipWhitelist": [
    "string"
  ],
  "domainWhitelist": [
    "string"
  ],
  "rateLimit": 0,
  "rateLimitWindow": 0,
  "status": "ACTIVE",
  "lastUsedAt": "2019-08-24T14:15:22Z",
  "usageCount": 0,
  "expiresAt": "2019-08-24T14:15:22Z",
  "rotatedFromId": "string",
  "rotatedAt": "2019-08-24T14:15:22Z",
  "revokedAt": "2019-08-24T14:15:22Z",
  "lastUsedIp": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Delete an API key

DELETE
/v1/api-keys/{id}

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

Path Parameters

idRequiredstring
curl -X DELETE "https://api.salesos.org/v1/api-keys/<string>" \
  -H "Authorization: Bearer <token>"

SuccessResponse

{
  "success": true
}

Revoke an API key

POST
/v1/api-keys/{id}/revoke

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

Path Parameters

idRequiredstring
curl -X POST "https://api.salesos.org/v1/api-keys/<string>/revoke" \
  -H "Authorization: Bearer <token>"

ApiKey

{
  "id": "string",
  "userId": "string",
  "organizationId": "string",
  "name": "string",
  "description": "string",
  "keyPrefix": "string",
  "scopes": [
    "string"
  ],
  "ipWhitelist": [
    "string"
  ],
  "domainWhitelist": [
    "string"
  ],
  "rateLimit": 0,
  "rateLimitWindow": 0,
  "status": "ACTIVE",
  "lastUsedAt": "2019-08-24T14:15:22Z",
  "usageCount": 0,
  "expiresAt": "2019-08-24T14:15:22Z",
  "rotatedFromId": "string",
  "rotatedAt": "2019-08-24T14:15:22Z",
  "revokedAt": "2019-08-24T14:15:22Z",
  "lastUsedIp": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Rotate an API key

Issues a new secret with the same settings. The old secret keeps working for overlapHours (default 24, 0 revokes it now), then expires.

POST
/v1/api-keys/{id}/rotate

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

Request Body

application/jsonRequired
overlapHoursnumber

Hours the old secret keeps working after rotation (0 revokes it immediately).

Default: 24Minimum: 0Maximum: 168

Path Parameters

idRequiredstring
curl -X POST "https://api.salesos.org/v1/api-keys/<string>/rotate" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "overlapHours": 24
  }'

ApiKeyRotated

{
  "id": "string",
  "userId": "string",
  "organizationId": "string",
  "name": "string",
  "description": "string",
  "keyPrefix": "string",
  "scopes": [
    "string"
  ],
  "ipWhitelist": [
    "string"
  ],
  "domainWhitelist": [
    "string"
  ],
  "rateLimit": 0,
  "rateLimitWindow": 0,
  "status": "ACTIVE",
  "lastUsedAt": "2019-08-24T14:15:22Z",
  "usageCount": 0,
  "expiresAt": "2019-08-24T14:15:22Z",
  "rotatedFromId": "string",
  "rotatedAt": "2019-08-24T14:15:22Z",
  "revokedAt": "2019-08-24T14:15:22Z",
  "lastUsedIp": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "key": "string",
  "previousKey": {
    "id": "string",
    "keyPrefix": "string",
    "status": "ACTIVE",
    "expiresAt": "2019-08-24T14:15:22Z"
  },
  "message": "string"
}

Regenerate an API key (replaces the secret with no overlap)

Deprecated, sunset 2027-04-01. Use /v1/api-keys/{id}/rotate.

POST
/v1/api-keys/{id}/regenerate

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

Path Parameters

idRequiredstring
curl -X POST "https://api.salesos.org/v1/api-keys/<string>/regenerate" \
  -H "Authorization: Bearer <token>"

ApiKeyRegenerated

{
  "id": "string",
  "key": "string",
  "keyPrefix": "string",
  "message": "string"
}

Get API key usage logs

GET
/v1/api-keys/{id}/usage

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

Path Parameters

idRequiredstring

Query Parameters

pagenumber
limitnumber
curl -X GET "https://api.salesos.org/v1/api-keys/<string>/usage?page=0&limit=0" \
  -H "Authorization: Bearer <token>"

ApiKeyUsagePage

{
  "logs": [
    {
      "id": "string",
      "apiKeyId": "string",
      "endpoint": "string",
      "method": "string",
      "statusCode": 0,
      "responseTimeMs": 0,
      "ipAddress": "string",
      "userAgent": "string",
      "requestId": "string",
      "errorMessage": "string",
      "createdAt": "2019-08-24T14:15:22Z"
    }
  ],
  "pagination": {
    "page": 0,
    "limit": 0,
    "total": 0,
    "totalPages": 0
  }
}

Get API key usage statistics

GET
/v1/api-keys/{id}/stats

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

Path Parameters

idRequiredstring
curl -X GET "https://api.salesos.org/v1/api-keys/<string>/stats" \
  -H "Authorization: Bearer <token>"

API Reference

Complete REST API reference for the SalesOS platform.

Users

User profile and preferences