Connected systems

A connected system is another piece of software that works with your workspace on its own: an ERP, a data warehouse, a nightly job. It signs in with a credential of its own rather than with somebody's account, pushes data into a dataset, starts a run, and collects the results on its own schedule. Nobody is at a keyboard and no browser is involved - that is the point of it. The work happens at three in the morning whether or not anyone is around.

What a connected system can do

A connected system works through the Automation API, and what it may do there is decided entirely by the access you grant its credential:

• Read the workspace - list the apps, the datasets it can write into, and the outputs it can read.
• Write data - import rows into a dataset of an analytic app, as a file it uploads and the workspace ingests.
• Run a pipeline - start a run and poll it until it finishes.
• Read results - generate an export of an output and download the file.

That is the whole surface. Whatever access you tick, a connected system cannot create or delete apps, change a pipeline, edit a Visualisation, invite people or change workspace settings. Those stay with the people in the workspace.

Where the credentials live

Open the Access page and its API credentials tab. A credential is a principal of the workspace like a member, so it is managed beside the members: who and what may work here is one page. The tab is for people allowed to manage the workspace's API credentials, which today means admins: a member is not offered it, and every request behind it is refused without that permission.

Each credential is one row of the tab's table: its name, its key, its access options, when it was last used, and when it expires or must next be attested. The gear on a row opens the credential's details, and the row's menu holds Attest, Edit access, Rotate secret and Revoke. Copy the key with the copy button beside it.

The details have three tabs: Details, Access and Activity. Access lists every permission its access options give it - reading app configuration, reading data, importing data files, running pipelines, downloading data, publishing - and which option gives each one, the same way a member's access is shown. A credential holds no role: it works in every shared space and every app in one, including apps created later, and never in anyone's personal space. A revoked credential can do nothing.

A credential is a workspace asset, not a personal one - it keeps working after whoever created it leaves. The list still names the person who issued it, and marks the credential Former member when that person is no longer in the workspace, so you have a prompt to review whether the integration is still wanted.

Take the tour of API credentials to be shown a credential, what rotating and revoking each cost, and the form that issues a new one. The tour never creates a credential - it stops at the button and waits for you.

Issuing one

New credential asks for a name, an optional description, and the access to grant. Name it after the system it is for ("ERP nightly import" rather than "test"), because that name is what the workspace's audit trail shows every time the integration writes something.

Creating it produces two strings:

• a Client ID, which identifies the credential and is safe to show; and
• a Client secret, which is what proves the system is that credential.

The secret is shown once. It is displayed in the dialog that appears right after you create the credential, and nothing can show it again: it is not stored in a form anyone, including an admin, can read back. If it is lost, rotate the credential to issue a new one. The dialog copies each one, or both at once as the environment variables OVIDENS_CLIENT_ID and OVIDENS_CLIENT_SECRET, and I've stored it closes it and discards the secret from the page.

Hand both to whoever builds the integration. Everything after that - how the system signs in with them, which endpoints it calls, what the file has to look like - is the developer's side of the work, and it is described by the API's own published contract rather than by this guide.

What the access options mean

Each option grants one kind of work and nothing else. The picker also prints the technical name each one carries in the API next to its label, which is what the developer building the integration will ask you about:

Two badges in the picker tell you how to read that list:

• Elevated marks an option that reaches beyond reading and running what the workspace has published - running a draft nobody has reviewed, for instance, or publishing, which changes what everyone in the workspace sees. An elevated option is an explicit choice you make for one integration, not something a new credential arrives with. Grant one only when the system genuinely needs it.
• Not in effect yet marks an option that nothing checks today. It is part of the vocabulary, so it can be granted, stored and shown, but granting it changes nothing an administrator could observe. The badge is the honest answer to "what does this actually do right now", and it disappears for an option as soon as that option starts taking effect.

Edit access changes the grant of an existing credential. Nothing has to be re-issued: the change applies from the credential's very next request, and taking access away binds even on a token the system is already holding.

Rotating the secret

Rotate secret issues a second secret without breaking anything. The secret in use today keeps working alongside the new one, so you can roll the new one out to the system at your own pace instead of during an outage. A credential never carries more than two secrets, so the next rotation is what retires the older one - rotating twice is the deliberate "stop accepting the old secret", and the dialog says so before you confirm it.

Rotate when a secret may have been exposed, when the person who set the integration up leaves, or on whatever schedule your own policy sets. The credential's details show when the current secret was created and when the previous one was last used, so you can watch the old secret go quiet before you retire it.

Telling whether it is working

Two places answer that, and they answer different questions:

• The credentials table says whether the credential is being used at all. Last used is the last time it authenticated, and reads "Never used" until the integration's first successful call - which makes it the first thing to check when a new integration is silent.
• The audit trail says what it actually did. Everything a connected system does is recorded like any other change: open the Audit Analytics app, go to All actions, and filter Actor kind to Integration. The Actor of a machine write is the integration itself, under the name its credential was given - not the administrator who issued that credential, because they authorised the machine, they did not perform the action. For how to read the trail, see Audit trail.

Credential events themselves - created, secret rotated, access changed, revoked - are in the same trail, attributed to the administrator who performed them, because there a person really did act.

Revoking

Revoke stops a credential immediately, including any token it is already holding: its next request is refused. It cannot be undone, so restoring access means issuing a new credential and giving the system its new secret.

A revoked credential stays in the list, marked Revoked and with nothing left to change but its key still copyable, and it keeps its name in the audit trail - so the record of what it did while it was live stays readable.