---
title: "SSW Public API – Getting Started"
slug: "ssw-public-api-getting-started"
updated: 2025-12-19T16:28:35Z
published: 2025-12-19T16:28:35Z
canonical: "docs.ssw.splashtop.com/ssw-public-api-getting-started"
excludeFromSearch: true
excludeFromExternalSearch: true
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ssw.splashtop.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SSW Public API – Getting Started

This section walks you through the basic steps to start using the **SSW APIs**, from creating an API key to making your first authenticated API call.

---

## 1. Create an API Key

SSW APIs use **API keys** as long-lived credentials. API keys are used **only to obtain access tokens** and **must not be used directly** to call business APIs.

---

### Steps

1. Log in to the **SSW Admin Console**
2. Click your **user avatar** in the top-right corner
3. Navigate to **API Keys**
4. Click **Add New**
5. Select the appropriate **API key type**
6. Save the generated **API Key ID** and **Secret Key**

> ⚠️ **Important** The secret key is shown **only once**. Store it securely.

---

### API Key Types

| API Key Type | Used For | Notes |
| --- | --- | --- |
| **Controller Key** | IAM / Controller APIs | Used for user, group, and application management |
| **Secrets Key** | Secrets (Vault) APIs | Used for reading and writing secrets |

> Each API key type is scoped to a specific service and **cannot be used interchangeably**.

---

## 2. Get an Access Token

SSW APIs use a **two-step authentication model**.

API keys are used only to authenticate and obtain **short-lived access tokens**. **All business APIs must be called using access tokens, not API keys.**

```
API Key → Authenticate → Access Tokens → Call APIs
```

---

## Authenticate API Key

Use your API key to exchange for access tokens.

---

### Endpoint

```
POST /iam/v1/apikey/authenticate
```

---

### Headers

```
Content-Type: application/json
```

---

### Request Body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `apikey` | string | Yes | API key token generated from the SSW Admin Console |

```
{
  "apikey": "<your_api_key>"
}
```

---

### Response

On success, the API returns **IAM and SDP access tokens**.

```
{
  "code": 0,
  "data": {
    "iam_token": "<iam_token>",
    "sdp_token": "<sdp_token>"
  },
  "message": "success"
}
```

---

## Token Types

| Token | Purpose |
| --- | --- |
| `iam_token` | Used for IAM-related APIs (users, groups, organizations) |
| `sdp_token` | Used for SDP-related APIs (applications, connectors, workspaces) |

---

## Token Characteristics

- Tokens are **short-lived**
- Tokens are **automatically scoped** based on the API key type
- Tokens must be included in the **Authorization** header
- API keys **must not** be used directly to call business APIs

---

## Example: Get Tokens Using cURL

```
curl -X POST "https://<your-ssw-host>/iam/v1/apikey/authenticate" \
  -H "Content-Type: application/json" \
  -d '{
    "apikey": "YOUR_API_KEY"
  }'
```

---

## Extract Tokens (Example using `jq`)

```
iam_token=$(jq -r '.data.iam_token' response.json)
sdp_token=$(jq -r '.data.sdp_token' response.json)
```

---

## Using the Token

Include the token in the `Authorization` header when calling APIs.

---

### Example: Call an SDP API

```
GET /sdp/v1/workspaces
Authorization: Bearer <sdp_token>
```

---

### cURL Example

```
curl -X GET "https://<your-ssw-host>/sdp/v1/workspaces" \
  -H "Authorization: Bearer $sdp_token"
```

---

## Error Handling

SSW APIs return standard HTTP status codes.

| HTTP Code | Description |
| --- | --- |
| 400 | Invalid request |
| 401 | Invalid or expired API key or token |
| 403 | API key not authorized |
| 429 | Rate limit exceeded |
| 500 | Internal server error |

---

[End-to-end example：Create / Import / Enable an Application](/v1/docs/end-to-end-examplecreate-import-enable-an-application) [End-to-End Example: Users & Groups (IAM APIs)](/v1/docs/end-to-end-example-users-groups-iam-apis) [Appendix: API Reference & Specifications](/v1/docs/appendix-api-reference-specifications)

## Attachments

- [secert-API-0.1.yml](https://download.ssw.splashtop.com/api-doc/secert-API-0.1.yml)
- [controller-API-0.1.yaml](https://download.ssw.splashtop.com/api-doc/controller-API-0.1.yaml)