Skip to main content

Authentication

The developer API supports server-side authentication. Public endpoints use one of two authentication models, and the model to use depends on the endpoint.

Choose an Authentication Method​

  • Admin session bearer token. Used only by the API key management endpoints. These require a bearer token copied from an active NeonNow Admin app session. See Admin session bearer token.
  • API key and access token. Used by scope-gated service endpoints. Create an API key with the required scopes, exchange it for a short-lived access token, then call the endpoint with that token. See API key and access token.

The generated API reference is the authoritative inventory of currently available operations.

A separate delegated OAuth flow exists for onboarded server-side integrations that act with a person's consent. It is not a public developer API operation. See Delegated server-side OAuth.

Both models keep credentials and token exchange on the integration's server. They must not be implemented in browser-only or mobile client code.

Admin Session Bearer Token​

Some endpoints are not scope-gated. They authenticate with a bearer token taken from an active NeonNow Admin app session. A way to manage this token in the NeonNow Admin app is planned but is not available yet, so for now a developer copies the token that the app already sends from the browser.

This model applies only to the API key management endpoints in the authentication service.

Copy the Token from an Active Session​

  1. Sign in to the NeonNow Admin app in your browser.
  2. Open the browser developer tools and select the Network tab.
  3. Reload the page or navigate so the app makes a request to the API. Filter the request list if it helps you find one.
  4. Select one of those requests and find the Authorization request header.
  5. Copy the token value that follows Bearer .
  6. Send that value on your own API calls in the Authorization header.
Authorization: Bearer ADMIN_SESSION_TOKEN

The token is tied to the admin session and is short-lived. Treat it as a secret. Do not embed it in browser code, mobile applications, source control, or logs. When it expires or the session ends the token stops working, so copy a fresh one from a current session when needed. This is a stopgap until the Admin app provides a managed way to do it, and it suits development and internal automation rather than a distributed integration.

API Key and Access Token​

API keys are organisation-scoped credentials for unattended integrations. Each key is a public client identifier plus a client secret. A key is created and managed through the key management operations, which themselves authenticate with an admin session bearer token:

  • POST /rest/v1/{organisationId}/key creates a key.
  • GET /rest/v1/{organisationId}/keys lists keys.
  • GET /rest/v1/{organisationId}/key/{id} reads a key.
  • PATCH /rest/v1/{organisationId}/key/{id} changes its metadata, expiry, or allowed scopes.
  • DELETE /rest/v1/{organisationId}/key/{id} revokes the key.

The client secret is returned only when the key is created. The administrator should transfer it through an approved secure channel, and the integration should store it in a secret manager. If the secret is lost, create a replacement key; it cannot be retrieved later.

Exchange a Key for an Access Token​

The integration's server exchanges the client identifier and secret for a short-lived access token at the token endpoint. The request fields and the response are documented on the access token operation in the generated Authentication API reference.

Send the access token with protected API requests:

Authorization: Bearer ACCESS_TOKEN

The integration should cache the token only for its valid lifetime and request a new token when required. It must not reuse a token after the underlying key has expired or been revoked.

Delegated Server-Side OAuth​

The delegated flow is a partial OAuth authorisation-code flow for onboarded integrations that act with a person's consent. The integration owns the user-facing redirect and callback. The platform-managed authentication service creates the provider consent URL and performs the code exchange.

The consent and exchange operations are available only to onboarded server-side integrations; they are not public developer API operations. Onboarding supplies the applicable service URLs and identity-provider name.

The integration's server requests a consent URL with:

  • identityProviderName: the configured provider.
  • redirectUri: an exact callback URI registered for the integration.
  • scopes: an array of provider scopes required for the integration.
  • state: a high-entropy, single-use value bound to the initiating browser session.

The authentication service returns a provider authorisation URL. The application redirects the person to this URL to review and approve access.

Only the minimum required scopes should be requested. The redirect URI used in this request must be reused unchanged during the token exchange.

2. Validate the Callback​

After consent, the provider redirects to the registered callback with a code and the original state.

The integration's server must reject the callback if state is missing, expired, already used, or does not exactly match the value stored for the initiating session. It must also handle provider error parameters when consent is denied or cannot be completed.

3. Exchange the Code​

The server sends the following values to the platform-managed token exchange:

{
  "identityProviderName": "CONFIGURED_PROVIDER",
  "redirectUri": "https://acme.example/oauth/callback",
  "code": "AUTHORISATION_CODE"
}

The response contains the provider token set. Tokens must be encrypted at rest, excluded from logs, and associated with the correct organisation and user connection. If a refresh token is issued, the same token operation can refresh the token set without repeating consent.

4. Use and Revoke the Token​

Send the access token as a bearer token when calling the resource covered by the approved provider scopes:

Authorization: Bearer ACCESS_TOKEN

When a connection is removed, the server should revoke the token through the platform-managed revocation operation and delete its stored token set.

Scopes​

Scopes limit what an access token can do. They apply to the API key and access token model. They are enforced in two places:

  1. The key's scope array defines the maximum permissions that the credential can request.
  2. The optional space-delimited scope sent to /token narrows permissions for that access token.

For example, ACME could assign a reporting integration only contact-flow-service:custom-schedule:read instead of broader write permissions. Separate keys should be used for separate integrations so each can be scoped, rotated, audited, and revoked independently.

Scope names are service-specific. Request only the scopes confirmed for the operations the integration calls. The generated reference is authoritative for which operations exist, but it does not currently identify each operation's required scope. The admin session bearer token model is not scope-gated, so it does not use these scope values. For base URLs and reference conventions, see Getting Started.