> For the complete documentation index, see [llms.txt](https://developer.switchmarket.se/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.switchmarket.se/getting-started/api-clients.md).

# API clients

Create and manage the client applications your integrations use to access the Switch platform's APIs.

To call any of the Switch platform's APIs, your integration needs a **client ID** and a **client secret**, which it exchanges for an access token. You get these by creating a client for your organization in the Switch app.

Each client works with exactly one API, decided by the **audience** you choose when you create it. If your integration uses more than one API, create a client for each.

{% hint style="info" %}
Only the owners of an organization can see and manage its clients.
{% endhint %}

## Choosing an audience

| API           | Audience            | What you select                                                          |
| ------------- | ------------------- | ------------------------------------------------------------------------ |
| Switch API    | **Switch API**      | Roles from your organization                                             |
| Metering API  | **Metering API**    | Scopes: `read`, `write`                                                  |
| OpenADR 3 VTN | **OpenADR VTN API** | Scopes: `read_all`, `write_reports`, `write_subscriptions`, `write_vens` |

The **OpenADR VTN API** audience is only available to organizations that have OpenADR enabled.

What each scope or role allows you to do is described in the authentication section of that API.

## View your clients

1. If you belong to more than one organization, first click the **User** icon in the top-right corner and choose the organization you want to manage clients for.
2. Click the **Settings** icon in the top-right corner, then click **My organization**.
3. In the left menu, click **API**.
4. The **Clients** tab lists your organization's clients, with the client ID of each.

## Create a client

1. On the **Clients** tab, click **Create client**.
2. Choose the **Audience** for the API the client will be used with.
3. Enter a **Name** that will tell you later what the client is used for.
4. Move what the client needs from **Available scopes** to **Selected scopes**. For the **Switch API** audience these are roles, so you move them from **Available roles** to **Selected roles** instead.
5. Click **Save**.

The new client appears in the list with its client ID and client secret.

{% hint style="danger" %}
**Copy the client secret straight away.** It is only shown until you refresh the page. After that you will only see a short hint of it, and if you lose it, the only way to get a working secret again is to rotate it.
{% endhint %}

A client's audience and name are fixed once it has been created. To use a client with a different API, create a new one.

## Change a client's scopes or roles

You can edit a client from the **Clients** tab to change its scopes or roles. Its name and audience cannot be changed.

{% hint style="warning" %}
Changing a client's scopes or roles changes what every integration using that client is allowed to do. Removing one can break an integration that depends on it.
{% endhint %}

## Rotate a client secret

1. On the **Clients** tab, click the rotate button next to the hint of the secret you want to replace, and confirm.
2. The new secret is shown until you refresh the page. Copy it straight away.

The old secret stops working as soon as you rotate it, so update every integration that uses this client with the new one.

## Delete a client

On the **Clients** tab, click **Delete** next to the client and confirm.

{% hint style="danger" %}
Any integration using a deleted client loses access to the API the client was created for.
{% endhint %}

## Next: request an access token

Each API explains how to exchange your client ID and client secret for an access token, and which token endpoint to use in each environment:

* [Metering API authentication](/metering-api/authentication.md)
* [Switch API authentication](/switch-api/authentication.md)
* [OpenADR 3 authentication](/openadr-3/authentication.md)