# Invite a user to a client

`POST /v0/labs/client/{client_id}/invite`

> **Authentication:** every request must send `X-ConfidentLims-APIKey`, `X-ConfidentLims-Timestamp` (unix seconds) and `X-ConfidentLims-Signature`, an HMAC-SHA256 signature of the request. The examples below call `sign_request()` from the [Request Signing guide](https://api.confidentcannabis.com/v0/docs/request-signing.md) — read it first. Request bodies are form-encoded (`application/x-www-form-urlencoded`), never JSON.

Invite a user to join one of your lab's clients. An email is sent to the
address with a link to create an account.

The client must already be associated with your lab, otherwise the request
returns `not_found`. Available organization roles are `owner`, `admin`, `user` and `viewer`.

Invites are rate limited; sending too many in quick succession returns HTTP
429.

## Path parameters

- `client_id` (integer, required)

## Body parameters (application/x-www-form-urlencoded)

- `email` (string (email), required) — Email address of the user to invite.
  Example: `sam@sunrisecultivation.com`
- `role` (string, required) — Organization role to grant: `owner`, `admin`, `user` or `viewer`.
  Allowed values: `admin`, `viewer`, `owner`, `user`
  Example: `admin`

## Responses

### 200 Success

Fields (alongside the `success: true` envelope flag):

- `invite` (object)
  - `id` (integer) — Invite ID
  - `email` (string) — User Email
  - `role` (string) — User Role

Example:

```json
{
  "success": true,
  "invite": {
    "id": 8123,
    "email": "sam@sunrisecultivation.com",
    "role": "admin"
  }
}
```

### 400 Bad request

The request was malformed or failed validation. Validation failures include per-field messages in `error_details`. Possible `error_code` values: `invalid_request`, `request_too_old`.

### 401 Unauthorized

Authentication failed. Possible `error_code` values: `missing_api_key`, `invalid_api_key`, `invalid_credentials_type`, `api_access_restricted`, `api_access_denied`, `missing_signature`, `missing_timestamp`, `invalid_timestamp`, `invalid_signature`.

### 403 Permission denied

The API key is valid but does not have permission for this endpoint (for example, a client key calling a labs endpoint). Possible `error_code` values: `permission_denied`.

### 404 Not found

The requested record does not exist or is not visible to this organization. Possible `error_code` values: `not_found`.

## Examples

### cURL

```bash
# X-ConfidentLims-Signature: see the Request Signing guide - https://api.confidentcannabis.com/v0/docs/request-signing.md
curl -X POST 'https://api.confidentcannabis.com/v0/labs/client/{client_id}/invite' \
  -H 'X-ConfidentLims-APIKey: YOUR_API_KEY' \
  -H 'X-ConfidentLims-Timestamp: UNIX_TIMESTAMP' \
  -H 'X-ConfidentLims-Signature: REQUEST_SIGNATURE' \
  --data-urlencode 'email=sam@sunrisecultivation.com' \
  --data-urlencode 'role=admin'
```

### Python

```python
import time
import requests

# sign_request() is defined in the Request Signing guide:
# https://api.confidentcannabis.com/v0/docs/request-signing.md
from sign_request import sign_request

API_KEY = 'YOUR_API_KEY'
API_SECRET = 'YOUR_API_SECRET'
path = '/v0/labs/client/{client_id}/invite'

data = {
    "email": "sam@sunrisecultivation.com",
    "role": "admin",
}

headers = {'X-ConfidentLims-Timestamp': str(int(time.time()))}
headers['X-ConfidentLims-Signature'] = sign_request(
    'POST', path, headers, data, API_KEY, API_SECRET)
headers['X-ConfidentLims-APIKey'] = API_KEY

response = requests.post(
    'https://api.confidentcannabis.com' + path,
    headers=headers,
    data=data,
)
print(response.json())
```

### JavaScript

```javascript
// signRequest() is defined in the Request Signing guide:
// https://api.confidentcannabis.com/v0/docs/request-signing.md
import { signRequest } from './sign_request.js';

const API_KEY = 'YOUR_API_KEY';
const API_SECRET = 'YOUR_API_SECRET';
const path = "/v0/labs/client/{client_id}/invite";

const data = {
  "email": "sam@sunrisecultivation.com",
  "role": "admin",
};

const headers = { 'X-ConfidentLims-Timestamp': String(Math.floor(Date.now() / 1000)) };
headers['X-ConfidentLims-Signature'] = signRequest(
  "POST", path, headers, data, API_KEY, API_SECRET);
headers['X-ConfidentLims-APIKey'] = API_KEY;

const response = await fetch("https://api.confidentcannabis.com" + path, {
  method: "POST",
  headers,
  body: new URLSearchParams(data),
});
console.log(await response.json());
```

---

HTML version: https://api.confidentcannabis.com/v0/docs/labs/post-client-invite  
OpenAPI spec for this section: https://api.confidentcannabis.com/v0/docs/labs/openapi.json  
Request Signing guide: https://api.confidentcannabis.com/v0/docs/request-signing.md