API access and credentials – access for other systems, and access to other systems¶
This chapter describes two kinds of definitions that connect nexxcite with other systems:
- API access lets an external system work with nexxcite through the REST API.
- Credentials hold the access data nexxcite uses to reach other systems – mail servers, file storage, AI services, directories.
It is intended for administrators who set up interfaces, and for operators who are responsible for the secrets involved.
1. At a glance¶
| API access | Credentials | |
|---|---|---|
| Direction | Another system → nexxcite | nexxcite → another system |
| Where | Admin Studio → Access → API Access | Admin Studio → Access → Credentials |
| Secret | Client secrets, generated by nexxcite, shown once | Passwords, keys and tokens of the other system, entered by you |
| How nexxcite keeps the secret | Only in a form that cannot be turned back into the secret | Readable, as part of the definition (section 8) |
| Permissions | "Open API Access Manager", "Add API Access", "Edit API Access", "Delete API Access" | "Open Credentials Manager", "Add Credentials", "Edit Credentials", "Delete Credentials" |
All these permissions are granted to system administrators by default. Neither kind of definition is accessible to the AI assistant.
Both can be saved without an open sketch. While a sketch is open, a change is collected in the sketch and takes effect only when the sketch is published (see Sketches and publishing).
2. API access – how it works¶
Summary¶
- An API access belongs to exactly one nexxcite user. Everything the external system does through the API runs with the roles and permissions of this user.
- The external system requests an access token with the client ID and a client secret of the API access (OAuth 2.0 "client credentials").
- A token is valid for one hour by default and takes a license like a user in a browser.
- A token can be revoked at any time in the session overview of the user.
Prerequisite on the server¶
The REST API authentication is switched off until a signing key is configured in appsettings.json
(section 9). Without it, the token endpoint answers every request with server_error.
3. Setting up an API access¶
- Create a dedicated user for the external system and give it a role with exactly the permissions and entity policies the system needs (see Users and Roles and permissions). A password is not needed.
- Open Admin Studio → Access → API Access and add an API access.
- In the tab "General", select the "User". The "Client ID" is generated automatically and cannot be changed.
- In the tab "Client Secrets", add a secret. Enter a "Label" (for example the name of the system that uses it) and check "Valid From" and "Valid To" – by default from now for one year.
- Click "Generate Secret". The secret is shown below the fields: "Copy this secret now. It is shown only once and cannot be recovered after the editor is closed. It becomes valid when the definition is saved - or, while a sketch is open, when the sketch is published."
- Copy the secret into the secure storage of the external system and save the API access.
Afterwards the editor only says "A secret is stored (hash only)". Neither you nor anybody else can display the secret again. If it is lost, generate a new one.
Note: Like other definitions, an API access is saved into the sketch if one is open. A new or replaced secret then only works after the sketch has been published, and the previous secret keeps working until then. To activate a secret right away, save the API access while no sketch is open.
Several secrets and rotation¶
An API access can have several secrets. Each one is valid between its "Valid From" and "Valid To". This allows a change without interruption:
- Add a second secret and generate it, save.
- Change the external system over to the new secret.
- Remove the old secret, save.
"Generate Secret" on a secret that already exists replaces it after a confirmation ("Replacing the secret invalidates the current one."). Every system that still uses the old secret can no longer request tokens.
A cloned API access gets a new client ID and no secrets.
4. Requesting and using a token¶
The external system requests a token with a POST request:
| Item | Value |
|---|---|
| Address | https://<address of your nexxcite installation>/api/oauth/token |
| Content type | application/x-www-form-urlencoded |
grant_type |
client_credentials |
client_id, client_secret |
In the request body, or as HTTP basic authentication |
The answer contains access_token, token_type ("Bearer") and expires_in (seconds). The system
then sends the token with every API request in the header Authorization: Bearer <token>, and
requests a new one when it has expired.
The interactive description of the REST API, including a way to try out the token request, is
available under /api/v1/docs unless it was switched off. The REST API chapter describes every endpoint; Authentication covers the token request in detail.
Errors¶
| HTTP status | error |
Cause |
|---|---|---|
| 400 | unsupported_grant_type |
grant_type is not client_credentials |
| 400 | invalid_request |
Client ID or client secret missing |
| 400 | temporarily_unavailable |
All licenses are in use. Try again later. (Without a valid license, every request is answered with 503 license_invalid before it reaches sign-in.) |
| 401 | invalid_client |
Unknown client ID; wrong secret or secret outside its validity; no user assigned; user locked or deleted |
| 500 | server_error |
No valid signing key configured on the server |
For security reasons, the answer does not distinguish between an unknown client ID and a wrong secret.
5. Tokens, sessions and licenses¶
Every token creates an API session of the assigned user. It appears in Admin Studio → Access → Authenticated Users, tagged "API", and in "User Sessions" with the name of the API access.
| Situation | Effect |
|---|---|
| A token is issued | The user takes a license – unless they already have one through another session or have a license-free role (see Licensing) |
| The token expires | The API session ends; the license is released at the latest about 5 minutes later |
| "Revoke" in User Sessions | The token stops working immediately, on every server |
| The assigned user is locked | All tokens of this user stop working immediately; no new tokens are issued |
| A secret is removed or the API access is deleted | No new tokens. Tokens requested with that secret stop working as soon as the change is published. |
| The server restarts | Valid tokens stay valid. With several servers, every server accepts the tokens of the others. |
For administrators
- To cut off a system at once, remove its secret or delete the API access and publish the change. Its open API sessions stay listed in "User Sessions" until they expire; revoke them there to release the license earlier.
- Keep the token lifetime moderate. A token is valid for its whole lifetime unless it is cut off as described above.
Tokens for the signed-in user¶
Besides the API access, an action can obtain a token for the user who is currently signed in, with
the system function CurrentUserApiAccessToken – for example to call another system that then works
with nexxcite on behalf of this user. The token has exactly the permissions of that user.
Every evaluation issues a new token and creates a new API session, which then also appears under "User Sessions" as "API access token of the signed in user". Use the function in actions, not in expressions that are evaluated over and over again (captions, grid cells, conditions). Treat the result like a password: never show it in a field, a log or an address.
6. Credentials – what they are for¶
A credentials definition holds the address and the access data of another system. Other definitions refer to it instead of containing the access data themselves – the same SMTP account can be used by many actions, and a changed password is changed in one place.
| Kind (menu entry) | Used for | Fields |
|---|---|---|
| "OpenAI Credentials" | AI assistants with Azure OpenAI or an OpenAI-compatible service | "API Schema", "Endpoint", "API Token", "API Version", "Structured Output" |
| "Anthropic Credentials" | AI assistants with Anthropic | "API Key", "Endpoint", "API Version" |
| "Azure Blob Storage Credentials" | Files and images in Azure Blob Storage | "Connection String", "Container" |
| "S3 Storage Credentials" | Files and images in S3-compatible storage | "Service URL", "Access Key", "Secret Key", "Bucket Name", "AWS Region", "Disable Certificate Validation", "Disable Checksum Validation" |
| "SMTP Credentials" | Sending mail from actions; the mail account of nexxcite | "Server Name", "Use Custom Port", "Port", "Security", "Authentication Required", "Username", "Password", "Disable Certificate Validation" |
| "IMAP Credentials" | Mailbox listeners | the same fields as SMTP |
| "Exchange Online Credentials" | Sending mail and mailbox listeners through Microsoft Exchange Online; the mail account of nexxcite | "Tenant ID", "Client ID", "Client Secret", "Mailbox" |
| "Microsoft Graph API Credentials" | Reading data from Microsoft Graph, for example profile pictures | "Tenant ID", "Client ID", "Client Secret" |
| "LDAP Credentials" | Actions that read and change a directory (users, groups, attributes) | "Domain", "Server", "Port", "Authentication Type", "Username", "Password", "Start Path" |
The "LDAP Credentials" are not used for signing in to nexxcite (see Authentication providers).
7. Setting up credentials¶
- Open Admin Studio → Access → Credentials, click the add button and choose the kind.
- Fill in the fields and save.
- Select the credentials where they are needed – in an action, a mailbox listener, an AI assistant, a files block or in the global settings ("Mail account", "Image File Provider Credentials").
nexxcite does not test the connection when you save. Errors appear only when the credentials are used, for example when an action sends a mail.
Disable Certificate Validation switches off the check of the server certificate. Use it only for test systems – it makes the connection open to interception.
8. How secrets are kept¶
Client secrets of API access¶
nexxcite stores only a value derived from the client secret, from which the secret cannot be recovered. The secret is shown exactly once, when it is generated.
Credentials¶
nexxcite has to send the passwords and keys of credentials to the other system, so it has to be able to read them. In the current version they are stored as part of the definition, without additional encryption by nexxcite. That means:
| Where | The secret is |
|---|---|
| The credentials editor | Visible in plain text to everybody who may open the credentials – except the LDAP password, which is masked |
| The database of nexxcite | Readable for whoever can read the definitions in the database |
| A sketch | Contained in the sketch if the credentials were changed while it was open – and in every sketch file downloaded from it |
| The AI assistant | Not accessible |
For administrators
- Grant the credentials permissions to as few people as possible. Whoever may open credentials can read the secrets.
- Protect the database and its backups like the systems the credentials give access to.
- Change credentials while no sketch is open, so that secrets do not end up in sketch files.
- Use dedicated accounts with only the rights nexxcite needs, for every credentials definition.
9. Settings for operation¶
The following values are set in appsettings.json, section ApiAuthentication. With several
servers, all of them must have the same values.
| Setting | Default | Meaning |
|---|---|---|
ApiAuthentication:SigningKey |
empty | Secret key the access tokens are signed with, at least 32 characters. Empty or shorter: the REST API authentication is off. Keep it out of source control. |
ApiAuthentication:Issuer |
nexxcite |
Issuer written into the tokens |
ApiAuthentication:Audience |
nexxcite-api |
Audience written into the tokens |
ApiAuthentication:AccessTokenLifetimeInSeconds |
3600 | How long a token is valid |
ApiDocumentation:Enabled |
true | Serves the interactive API description under /api/v1/docs |
Changing the signing key makes all tokens issued before invalid. External systems then simply request new ones.
10. Limitations¶
- Removing a client secret or deleting an API access does not end tokens already issued (section 5).
- The token endpoint has no limit on the number of requests. Client secrets are long random values and cannot be guessed in practice.
- Secrets of credentials are stored without additional encryption and are visible in the editor (section 8).
- An API access can only use the client credentials method. Other OAuth 2.0 methods are not offered.
- nexxcite does not test credentials when they are saved.
11. Frequently asked questions¶
I have lost the client secret. Can I display it again? No. Generate a new secret, give it to the external system and save.
Does an API access need a password for its user? No. The user only needs the roles that the external system requires.
Does an external system take a license? Yes, while it holds a valid token – unless its user has a license-free role or is already signed in elsewhere.
Does two-factor authentication apply to the REST API? No. API access uses its own credentials; the two-factor settings concern the sign-in page only.
Can the same credentials be used in several places? Yes. That is their purpose. A change applies everywhere they are used.
Can the AI assistant read credentials or client secrets? No. Credentials and API access are not accessible to the AI assistant.