> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-cloud/api/authentication/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Platform Cloud API authentication

> Secure your API requests using basic, query token, or client authentication.

API requests without authentication fail. The following authentication methods are available:

* [Basic](#basic-authentication) – Username and password
* [Query token](#query-token-authentication) – Auth token in query header
* [Client](#client-authentication) – Bearer token

---

## Basic authentication

### Overview

Send credentials in the HTTP request `Authorization` header as a base64-encoded `username:password` string.

### Example

Replace `username` and `password` with your credentials:

```curl
curl -u username:password -X GET "https://localhost:3443"
```

### HTTP request header

```shell
Authorization: Basic base64(username:password)
```

For example, if your username is `user` and your password is `pass`, the encoded header looks like this:

```shell
Authorization: Basic dXNlcjpwYXNz
```

Basic authentication is only available over SSL.

### Validate your credentials

Send a `GET` request to `whoami` to confirm you can reach theItential Platform server API and view access associated with your user:

```curl
curl -u username:password -X GET "https://localhost:3443/whoami"
```

---

## Query token authentication

### Overview

Obtain a token by sending a `POST` request to `/login`, then pass the token as a query parameter in subsequent requests.

### Request a token

Send a `POST` request to `/login` with the following JSON payload:

```json
{ "user": { "username": "admin", "password": "admin" } }
```

#### Example

```curl
curl -X POST "https://localhost:3443/login" \
  -H "Content-Type: application/json" \
  -d '{"user": {"username": "admin", "password": "admin"}}'
```

#### Response

A successful login returns an authentication token:

```shell
your-auth-token-here
```

### Use the token

Include the token as a query parameter in subsequent requests:

```shell
?token=your-auth-token-here
```

### Validate your token

Replace `your-auth-token-here` with the token returned by `/login`:

```curl
curl -X GET "https://localhost:3443/whoami?token=your-auth-token-here"
```

---

## Client authentication

### Overview

Obtain a bearer token by sending a `POST` request to `/oauth/token`, then pass the token in the `Authorization` header of subsequent requests.

### Request a token

Send a `POST` request to `/oauth/token` with `Content-Type: application/x-www-form-urlencoded` and the following payload:

```shell
client_id=your-client-id&client_secret=your-client-secret&grant_type=client_credentials
```

#### Example

```curl
curl -X POST "https://localhost:3443/oauth/token" \
  -H "Accept: application/json" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'client_id=123abccc123a123a12ab1ab1&client_secret=a123a123-a1a1-1a1a-a123-123a12abc1a1&grant_type=client_credentials'
```

#### Response

A successful request returns the bearer token and its expiration time:

```json
{
  "access_token": "falksjflkasdjflkasdjfklajsdflj.eyJwcmluY2lwYWxJZCI6IjY2OWU1ZGNjOTE1ZDUxMWEzMmJmMGNhNCIsImV4cCI6MTcyMTY1OTQ4MDkwMiwiaWF0IjoxNzIxNjU1ODgwfQ.7jrB2mC9aqSdPdUvz7D-u9HghRFtnpFbYdaBH54kNZc",
  "token_type": "bearer",
  "expires_in": 3600
}
```

### Use the token

Set the `access_token` value as your `Authorization` header:

```shell
Authorization: Bearer your-access_token-here
```

### Validate your token

Replace `your-access_token-here` with the token returned by `/oauth/token`:

```curl
curl -X GET "https://localhost:3443/whoami" \
  -H "Authorization: Bearer your-access_token-here"
```

> Secure your API requests using basic, query token, or client authentication.