Introduction

Get started with the SendKit API

Authenticate with the SendKit Platform API, call your first endpoints, and understand platform vs workspace API keys and headers.

Overview

Authenticate with the SendKit Platform API, call your first endpoints, and learn how platform and workspace API keys affect which headers you send.

Prerequisites

A SendKit account
At least one API key:
- Workspace key starting with sk_... or
- Platform key starting with sk_user_...
Workspace ID (only required when using a platform key with workspace-scoped endpoints)

Keep your keys secret. Do not commit them to source control or expose them in client-side code.

Authentication options

SendKit supports two authentication styles and two key types. All requests go to:

https://api.sendkit.ai

API key locations

You can send your key using either a custom header or a bearer token:

API key header
```
X-Api-Key: sk_...
```
Bearer token header
```
Authorization: Bearer sk_...
```

Use one style per request; both authenticate the same key.

Platform vs workspace keys

Key types and workspace scoping

Workspace keys (sk_...): Already scoped to a single workspace. Do not send X-Workspace-Id.
Platform keys (sk_user_...): Can act across multiple workspaces. For workspace-scoped endpoints, you must send X-Workspace-Id to select which workspace the request targets.

Step 1: Call `/v1/account` (no workspace required)

Start by verifying your key with a non-workspace endpoint.

Send GET /v1/account

Use either X-Api-Key or Authorization: Bearer with your key. This endpoint does not require X-Workspace-Id.

curl https://api.sendkit.ai/v1/account \
  -H "X-Api-Key: sk_live_a9XyP4uvQ1LnR7bzK3mH2wD8"

import https from "https";

const req = https.request(
  "https://api.sendkit.ai/v1/account",
  {
    method: "GET",
    headers: {
      "Authorization": "Bearer sk_live_a9XyP4uvQ1LnR7bzK3mH2wD8"
    }
  },
  (res) => {
    let data = "";
    res.on("data", (chunk) => (data += chunk));
    res.on("end", () => {
      console.log("Status:", res.statusCode);
      console.log("Body:", data);
    });
  }
);

req.on("error", (err) => {
  console.error("Request error:", err);
});

req.end();

import requests

url = "https://api.sendkit.ai/v1/account"
headers = {
    "X-Api-Key": "sk_live_a9XyP4uvQ1LnR7bzK3mH2wD8"
}

response = requests.get(url, headers=headers)
print("Status:", response.status_code)
print("Body:", response.text)

Confirm a successful response

You should see a 200 OK response with basic account details. A typical response shape looks like this:

{
  "id": "acct_9Lm3qBv72DxGkP5r",
  "email": "dev-team@acme-mail.io",
  "name": "Acme Messaging",
  "created_at": "2024-02-18T11:32:07.283Z",
  "default_workspace_id": "ws_3Kp9vQm6NdZ2wX8a"
}

If you receive 401 or 403, see Troubleshooting.

Step 2: Call a workspace-scoped endpoint

Next, call an endpoint that is sensitive to workspace scoping: GET /v1/workspaces.

Choose headers based on your key type

If you use a workspace key (sk_...):
- Authenticate with X-Api-Key or Authorization: Bearer.
- Do not send X-Workspace-Id; the key is already scoped.
If you use a platform key (sk_user_...):
- Authenticate with X-Api-Key or Authorization: Bearer.
- For workspace-scoped endpoints that require a specific workspace, send:
```
X-Workspace-Id: ws_...
```

Send GET /v1/workspaces

The examples below show a workspace key. To use a platform key, replace the key value and, when required by the endpoint, add the X-Workspace-Id header.

curl "https://api.sendkit.ai/v1/workspaces" \
  -H "X-Api-Key: sk_live_a9XyP4uvQ1LnR7bzK3mH2wD8"

import https from "https";

const req = https.request(
  "https://api.sendkit.ai/v1/workspaces",
  {
    method: "GET",
    headers: {
      "Authorization": "Bearer sk_live_a9XyP4uvQ1LnR7bzK3mH2wD8"
      // For platform keys, add:
      // "X-Workspace-Id": "ws_3Kp9vQm6NdZ2wX8a"
    }
  },
  (res) => {
    let data = "";
    res.on("data", (chunk) => (data += chunk));
    res.on("end", () => {
      console.log("Status:", res.statusCode);
      console.log("Body:", data);
    });
  }
);

req.on("error", (err) => {
  console.error("Request error:", err);
});

req.end();

import requests

url = "https://api.sendkit.ai/v1/workspaces"
headers = {
    "X-Api-Key": "sk_live_a9XyP4uvQ1LnR7bzK3mH2wD8"
    # For platform keys, add:
    # "X-Workspace-Id": "ws_3Kp9vQm6NdZ2wX8a"
}

response = requests.get(url, headers=headers)
print("Status:", response.status_code)
print("Body:", response.text)

Verify workspace data

A successful response returns workspace records, for example:

{
  "data": [
    {
      "id": "ws_3Kp9vQm6NdZ2wX8a",
      "name": "Transactional email",
      "created_at": "2024-01-05T09:14:22.914Z"
    }
  ]
}

If you use a platform key and see authorization errors on workspace-scoped endpoints, confirm you are sending the correct X-Workspace-Id.

Troubleshooting common errors

401 Unauthorized

The API could not authenticate your request.

Confirm you are sending one of:
- X-Api-Key: your_key
- Authorization: Bearer your_key
Check for:
- Typos in the key value
- Extra spaces or quotes around the key
- Using a revoked or test key in a live environment

403 Forbidden

The request is authenticated but not allowed.

Verify the key type has access to the endpoint:
- Platform keys may need additional permissions.
If you use a platform key on a workspace-scoped endpoint:
- Add the correct X-Workspace-Id.
- Ensure the workspace ID matches a workspace the key can access.
If you use a workspace key, confirm the endpoint supports that workspace.

If issues persist, log the full response body and status code and compare your request shape with the API Reference.

Next steps

Explore the full endpoint catalog and schema details in the API Reference tab of the docs. Use it to:

Find additional account and workspace operations
Discover messaging, templates, and event endpoints
Inspect request and response structures backed directly by the OpenAPI specification

Was this page helpful?

Last updated today

Built with Documentation.AI