Generating an Organisation Client ID and Client Secret

Overview

Call the Vortex IQ Automations API server-to-server using a Bearer token. To obtain that token, log in at:

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.

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.

Open the admin login page in your browser:

https://app.vortexiq.ai/admin/login

Step 2 - Open Automations Access

After signing in, use the left sidebar. Scroll to the VORTEXSPACE section and click Automations Access.

This opens the Automations - Access page:

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.

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.

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.

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.

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.

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).

Every issue, rotate, and disable records the acting admin and timestamp for audit.

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).

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.

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.

POST /v2/api/automations/login
Content-Type: application/json

Request Body

{
  "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:

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.

You have successfully generated and managed an Organisation Client ID and Client Secret for use with the Vortex IQ Automations API.

Choose your outcome

Get Started

The AI OS

Generating an Organisation Client ID and Client Secret

Overview

Prerequisites

Step 2 - Open Automations Access

Step 3 - Choose the organisation

Step 4 - Issue the Client ID and Client Secret

Step 5 - Managing an issued credential

API Documentation

Quick Troubleshooting

​Overview

​Prerequisites

​Step 1 - Sign in to the Admin Portal

​Step 2 - Open Automations Access

​Step 3 - Choose the organisation

​Step 4 - Issue the Client ID and Client Secret

​Step 5 - Managing an issued credential

​Sharing the credentials

​Bearer Token Login Request

​API Documentation

​Quick Troubleshooting

Overview

Prerequisites

Step 1 - Sign in to the Admin Portal

Step 2 - Open Automations Access

Step 3 - Choose the organisation

Step 4 - Issue the Client ID and Client Secret

Step 5 - Managing an issued credential

Sharing the credentials

Bearer Token Login Request

API Documentation

Quick Troubleshooting