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

# SDK API

> Create client sessions, read link sessions and read chargers from your server.

The SDK API is what your server calls for the Plugchoice SDK. It creates the client sessions your app hands to Link, reads the link sessions Link opened, and reads chargers with what each can do.

It isn't the Plugchoice API (`/v3`): it has its own base URL, credentials, versions and error format.

## Base URL

```
https://api.plugchoice.com/sdk/v1
```

## Authentication

Call the SDK API from your server only. Your app never sees your credentials: it gets a short-lived client secret through your own endpoint (see [Get started](/sdk/get-started)).

### Integrations

An integration has a client ID and a client secret; it starts in test mode. Exchange them for an access token with the OAuth client credentials grant:

```bash theme={null}
curl -X POST https://app.plugchoice.com/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET
```

```json theme={null}
{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJ0..."
}
```

The token lasts an hour and acts as your integration's team. Keep it on your server, reuse it until it expires, then request a new one. Send it in the `Authorization` header:

```bash theme={null}
curl https://api.plugchoice.com/sdk/v1/chargers \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Plugchoice-Version: 2026-10-07"
```

To get an integration, email [support@plugchoice.com](mailto:support@plugchoice.com). See [Test and live](/sdk/concepts/test-and-live).

<Warning>
  Keep your client ID and secret on your server. Never put them in your app.
</Warning>

### Plugchoice users

A Plugchoice user can call the SDK API with their own OAuth access token or personal access token (see [Authentication](/guides/authentication)). They then act for themselves: their client sessions reach the chargers and sites they have Sensitive access to, and their link sessions show no consent screen.

## Versions

The SDK API is versioned by date. Send the version you built against in the `Plugchoice-Version` header:

```
Plugchoice-Version: 2026-10-07
```

* Without the header you get the newest version. Pin it, so a new version never changes what your server reads.
* Every response says which version answered, in the same header.
* An unknown version is [`400 unknown-version`](/sdk/errors/unknown-version).

`2026-10-07` is the only version. See [Versions](/sdk/versioning).

## Errors

Errors are [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem details, with `Content-Type: application/problem+json`:

```json theme={null}
{
  "type": "https://developer.plugchoice.com/sdk/errors/scope-required",
  "title": "A scope is required",
  "status": 422,
  "code": "scope-required",
  "detail": "Name the chargers, the sites, the address or a new site (`scope`) this client session may reach."
}
```

Switch on `code`; `type` links to its page. New codes may be added. See [Errors](/sdk/errors).

## Rate limits

Each integration or Plugchoice user may make 120 requests a minute. Over it, the API answers [`429 rate-limited`](/sdk/errors/rate-limited) with a `Retry-After` header in seconds.

## Pagination

[List chargers](/sdk/api/list-chargers) returns a page at a time, newest first:

* `limit`: 1 to 100, 25 by default.
* `cursor`: the `next_cursor` of the previous page. `next_cursor` is `null` on the last page.

## Conventions

* Ids are UUIDs.
* Times are RFC 3339, in UTC.
* Ignore fields and values you don't know: new ones may be added within a version.

## Endpoints

<Columns cols={2}>
  <Card title="Create a client session" icon="key" href="/sdk/api/create-client-session">
    Say who Link acts for, and what it may reach.
  </Card>

  <Card title="Get a link session" icon="circle-check" href="/sdk/api/get-link-session">
    Confirm what happened in Link.
  </Card>

  <Card title="List chargers" icon="list" href="/sdk/api/list-chargers">
    Your chargers, with their capabilities.
  </Card>

  <Card title="Get a charger" icon="plug" href="/sdk/api/get-charger">
    One charger, with its capabilities.
  </Card>
</Columns>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.