Identity Server

The Identity Server issues access tokens used to call NG-SOS APIs. Partner server applications normally use the client_credentials grant at POST /connect/token.

Values supplied during onboarding

Before implementing the integration, obtain these values from NG-SOS:

Value	Purpose
`client_id`	Identifies your application.
`client_secret`	Authenticates your application. Keep it on the server and never expose it in browser or mobile code.
Allowed scopes	Determine which NG-SOS operations the application may call.
Allowed agency IDs	Determine the agencies on whose behalf the application may act.

Production Identity Server URL:

https://identity.ng-sos.com

Request an application token

Send the token request as application/x-www-form-urlencoded. Do not send JSON.

POST /connect/token HTTP/1.1
Host: identity.ng-sos.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&scope=incident.close&resource=ems

Equivalent cURL request:

curl --request POST "https://identity.ng-sos.com/connect/token" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=YOUR_CLIENT_ID" \
  --data-urlencode "client_secret=YOUR_CLIENT_SECRET" \
  --data-urlencode "scope=incident.close" \
  --data-urlencode "resource=ems"

Parameters:

Parameter	Required	Value
`grant_type`	yes	`client_credentials`
`client_id`	yes	Client ID supplied by NG-SOS.
`client_secret`	yes	Client secret supplied by NG-SOS.
`scope`	yes	One or more space-separated scopes assigned to the client.
`resource`	no	OAuth resource indicator. Restricts the token's `aud` to a resource granted by the requested scopes; unsupported targets are rejected with `invalid_target`.
`agency_context`	no	Agency UUID. Include it when the called API operates in an agency context.
`psap_id`	no	Deprecated fallback for `agency_context`. Never send both parameters.
`username`	conditional	Include only for a user-context token as described below.

A successful response has this shape:

{
  "access_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "incident.close"
}

Cache and reuse the access token until shortly before expires_in. Do not request a new token before every API call.

Add agency context

Include agency_context when the target API must know which agency the application represents:

curl --request POST "https://identity.ng-sos.com/connect/token" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=YOUR_CLIENT_ID" \
  --data-urlencode "client_secret=YOUR_CLIENT_SECRET" \
  --data-urlencode "scope=incident.caller.live-video" \
  --data-urlencode "agency_context=123e4567-e89b-12d3-a456-426614174000"

The value must be an agency UUID assigned to the client during onboarding. The resulting access token contains the agency_context claim. Request a separate token for each agency context. Existing integrations may continue to send psap_id as a deprecated fallback, but a request containing both names is rejected.

Request a user-context token

Some operations must run as a concrete NG-SOS user instead of only as an application. For this variant, all of the following are required:

The client is assigned the username.required scope.
The request includes username.required together with the business scopes required by the API operation.
The request includes both agency_context and username.
The client is allowed to use the specified agency and the user exists in that agency.

curl --request POST "https://identity.ng-sos.com/connect/token" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=YOUR_CLIENT_ID" \
  --data-urlencode "client_secret=YOUR_CLIENT_SECRET" \
  --data-urlencode "scope=username.required incident.caller.live-video" \
  --data-urlencode "agency_context=123e4567-e89b-12d3-a456-426614174000" \
  --data-urlencode "username=dispatcher@example.com"

For this token, sub identifies the resolved user rather than the client. The token also contains the client_id, agency_context, username, name, email and role claims available for that user.

Do not send username without the username.required scope. Such a request is rejected with invalid_request.

Call an NG-SOS API

Send the access token in every protected request:

GET /v1/agency/info HTTP/1.1
Host: api.ng-sos.com
Authorization: Bearer YOUR_ACCESS_TOKEN

Use the API reference for the called operation to determine its required scope and whether it needs agency or user context.

Handle token errors

Token errors use this JSON shape:

{
  "error": "invalid_scope",
  "error_description": "The specified scope is not allowed."
}

Common failures:

Error	Meaning
`invalid_client`	The `client_id` or `client_secret` is invalid.
`invalid_scope`	The client is not assigned one or more requested scopes.
`invalid_target`	The requested `resource` is not granted by the requested scopes.
`ValidationFailed`	`agency_context` is invalid or was combined with its deprecated `psap_id` alias.
`invalid_request`	A required parameter is missing or `username` was sent without `username.required`.
`PSAP ID invalid`	`psap_id` is not an agency UUID.
`PSAP not allowed`	The client is not allowed to act for the requested agency.
`access_denied`	The required user context cannot be resolved or is not allowed.

Log the HTTP status, error and error_description, but never log client_secret or access tokens.

Other configured token grants

The server also supports authorization_code with mandatory PKCE and refresh_token. Use these grants only when NG-SOS explicitly configures the client for an interactive login integration.

The exact request parameters are listed in the Identity API Reference. Protocol details are defined by OAuth 2.0 and PKCE.

An authorized partner can sign a user into the NG-SOS Portal without asking for the user's NG-SOS password. See the complete Passwordless sign-in guide for the flow, security considerations and cURL examples.

Use case	Flow
The user should choose or complete an interactive sign-in	Preselect an agency before sign-in
A trusted backend already knows the user and should open the Portal without a password prompt	Passwordless sign-in

Values supplied during onboarding​

Request an application token​

Add agency context​

Request a user-context token​

Call an NG-SOS API​

Handle token errors​

Other configured token grants​

Passwordless Portal sign-in​

Passwordless sign-in versus agency preselection​

References​