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

# Generating an Organisation Client ID and Client Secret

> Generate Automations API credentials (a client_id and client_secret) for an organisation

## Overview

Call the Vortex IQ Automations API server-to-server using a Bearer token.

To obtain that token, log in at:

```text theme={null}
POST https://app.vortexiq.ai/v2/api/automations/login
```

using your identity:

* username
* email
* organisation name

PLUS a per-organisation API credential:

* client\_id
* client\_secret

That credential is issued by a VortexIQ admin from the **Automations Access** page in the admin portal.

This guide walks you through the navigation and the issuing process step by step.

> [!NOTE]
>
> * It is generated by the system - nobody chooses the values.
> * The **client\_id** is permanent for the organisation.
> * The **client\_secret** is random and regenerated on every issue/rotate.
> * The **client\_secret** is displayed **EXACTLY ONCE**, at the moment it is issued.
> * Only a hash is stored server-side; it can never be retrieved again.
> * If it is lost, rotate it.
> * Rotating or disabling the credential invalidates every API token issued with it, on its next call.
> * A token made with the credential can never approve a run's changes: approvals stay in the Vortex IQ app.

***

## Prerequisites

* A VortexIQ admin account with access to the admin panel and the VortexSpace management permission.
* The customer organisation must exist in VortexIQ, with Automations switched on (this same page manages that).
* The person who will log in must be an **active** VortexIQ user of that organisation.

***

## Step 1 - Sign in to the Admin Portal

Open the admin login page in your browser:

```text theme={null}
https://app.vortexiq.ai/admin/login
```

Sign in with your admin email address and password.

![Automations Client ID Secret 01](https://mintcdn.com/vortexiq/fYkLguxofvs2sui-/images/AutomationsClientIDSecret-01.png?fit=max\&auto=format\&n=fYkLguxofvs2sui-\&q=85\&s=ca54ff459fbec7995c5ddb351b212eb0)

***

## Step 2 - Open Automations Access

After signing in, use the left sidebar.

Scroll to the **VORTEXSPACE** section and click **Automations Access**.

![Automations Client ID Secret 02](https://mintcdn.com/vortexiq/fYkLguxofvs2sui-/images/AutomationsClientIDSecret-02.png?fit=max\&auto=format\&n=fYkLguxofvs2sui-\&q=85\&s=6e2f6417bd8c34f7f27a38e3061f104c)

This opens the **Automations - Access** page:

```text theme={null}
https://app.vortexiq.ai/admin/vortexspace/automations-access
```

***

## Step 3 - Choose the organisation

Select the organisation in the **Organization** list, then click **Check current state**.

The page shows two things:

* **State** - whether Automations are switched **on** or **off** for the organisation. An organisation that is off
  cannot use the API: every call answers `403`. To switch it on, enter a reason (optional) and click **Switch on**.
* **API credential** - the organisation's credential, or **none issued**.

![Automations Client ID Secret 03](https://mintcdn.com/vortexiq/fYkLguxofvs2sui-/images/AutomationsClientIDSecret-03.png?fit=max\&auto=format\&n=fYkLguxofvs2sui-\&q=85\&s=5109b143758e319bb546df111977be93)

***

## Step 4 - Issue the Client ID and Client Secret

Click **Issue credential** under **API credential** (the button reads **Rotate credential** once the organisation has one) and confirm.

The page reloads with an amber banner showing the freshly generated pair - **THIS IS THE ONLY TIME THE SECRET IS EVER DISPLAYED**.

> [!WARNING]
>
> The **client\_secret** is displayed **ONLY ONCE**.
>
> Copy **both** the **client\_id** and **client\_secret** immediately.
>
> If the secret is lost, it **cannot be retrieved**. Rotate the credential to generate a new secret.

![Automations Client ID Secret 04](https://mintcdn.com/vortexiq/fYkLguxofvs2sui-/images/AutomationsClientIDSecret-04.png?fit=max\&auto=format\&n=fYkLguxofvs2sui-\&q=85\&s=a51323f24d8e33bbce9cf34155ccafa5)

The banner displays:

* **client\_id** - the organisation's permanent public identifier (starts with **viq\_auto\_**).
* **client\_secret** - the private key. Copy it **NOW** and store it in a password manager. Only a hash is kept server-side.

> [!NOTE]
>
> The values visible in the screenshots of this guide are examples for illustration.

***

## Step 5 - Managing an issued credential

Choose the organisation again and click **Check current state**: the **API credential** line shows the live state.

![Automations Client ID Secret 05](https://mintcdn.com/vortexiq/fYkLguxofvs2sui-/images/AutomationsClientIDSecret-05.png?fit=max\&auto=format\&n=fYkLguxofvs2sui-\&q=85\&s=f27587f04dc4ab1ef286c75e5c78b818)

* **enabled** - API login is active for this organisation.
* The value after it is the **client\_id**; **"...QsPx"** shows the last 4 characters of the current secret; the **v** number is the secret version (it rises on every rotate or disable).
* **Rotate credential** - generates a **NEW** secret (same **client\_id**), shows it once in the banner, and invalidates the old secret and every outstanding API token for the organisation on its next call. Use when a secret is lost or compromised, or for periodic hygiene. The page asks you to confirm.
* **Disable credential** - switches the organisation's API access off without touching their use of the Vortex IQ app. Every outstanding token stops working on its next call. **Issue credential** turns it back on with a fresh secret.
* If the line ends with *the Automations service has not been told of this change*, the change was saved here but the service could not be reached at that moment: repeat the action (rotate, or disable) once it answers, and check the state again.
* **Switch off** - switches Automations off for the organisation (its automation screens and the API).

> [!NOTE]
>
> Every issue, rotate, and disable records the acting admin and timestamp for audit.

## Sharing the credentials

Deliver the **client\_id** and **client\_secret** to the customer through a **SECURE** channel - a password manager share or a one-time secret link.

Never send the secret in plain email or chat.

Tell the customer the three identity values must match their VortexIQ account exactly:

* **username** - their name as registered on their VortexIQ user (first name, last name, or full name).
* **email** - the email of their VortexIQ user account.
* **organization\_name** - their organisation name exactly as registered (case-insensitive).

> [!WARNING]
>
> The customer must provide all of the following values exactly as registered:
>
> * username
> * email
> * organization\_name
> * client\_id
> * client\_secret
>
> Any mismatch will prevent successful authentication.

***

## Bearer Token Login Request

With those plus the credentials, they log in and receive a Bearer token valid for 60 minutes.

The customer authenticates by calling the login endpoint.

```http theme={null}
POST /v2/api/automations/login
Content-Type: application/json
```

Request Body

```json theme={null}
{
  "username": "John Smith",
  "email": "john.smith@example.com",
  "organization_name": "Acme Inc",
  "client_id": "viq_auto_xxxxxxxxxxxxxxxxxxxxxxxx",
  "client_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
```

If authentication succeeds, the API returns a Bearer token, the scopes it holds, its expiry, and the address of the Automations API (`https://automations-api.vortexiq.ai`).

The customer supplies this token in the **Authorization** header for all subsequent Automations API requests. When it expires after 60 minutes, they simply log in again.

***

## API Documentation

Complete API documentation is available at:

```text theme={null}
https://docs.vortexiq.ai/automations/api/overview
```

The documentation includes:

* Authentication
* Templates and stores
* Automation endpoints
* Runs, schedules and the calendar
* Request and response examples
* Error responses
* API reference

***

## Quick Troubleshooting

> **The client\_secret was lost**
>
> The secret cannot be recovered.
>
> Click **Rotate credential** to generate a new secret.
>
> Share the newly generated secret securely with the customer.

> **401 - Invalid credentials**
>
> Verify that:
>
> * username matches the VortexIQ user.
> * email matches the VortexIQ user, and the account is active.
> * organization\_name matches the organisation.
> * client\_id is correct.
> * client\_secret is the latest version.
>
> If necessary, rotate the credential and try again.

> **403 - Automations are switched off for this organisation**
>
> The organisation's Automations are switched off. Choose it on **Automations Access**, click **Check current
> state**, and **Switch on**.

> **403 - This token may not do this: it needs the scope automations:approve**
>
> Approving and rejecting a run's changes happen in the Vortex IQ app: a credential's token never holds that
> scope. An endpoint outside this documentation answers `403 This route is not part of the Automations API`.

> **Bearer token suddenly stopped working**
>
> The token may have expired (after 60 minutes), or the credential may have been:
>
> * Rotated
> * Disabled
>
> Either action invalidates all previously issued Bearer tokens on their next call.
>
> Authenticate again using the latest client credentials.

***

> [!TIP]
>
> You have successfully generated and managed an Organisation **Client ID** and **Client Secret** for use with the Vortex IQ Automations API.


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