Table of Contents

Identity Server

Every ERP.net instance includes a built-in Identity Server that acts as its authentication and authorization authority.

It handles sign-in, token issuance, and access control for all users, apps, and services that connect to the instance.

What the Identity Server does

The Identity Server is responsible for:

  • Authenticating users and service accounts
  • Applying instance-level security and sign-in policies
  • Issuing OAuth 2.0 tokens used to access ERP.net APIs
  • Managing logout and session lifecycles

Think of it as the gatekeeper of an ERP.net instance: it verifies who is requesting access, confirms what they are allowed to do, and issues a signed token if the request is permitted.

Note

The Identity Server acts as both an authorization server (issuing tokens) and an authentication server (verifying credentials).

Identity Server location

Each ERP.net instance hosts its own Identity Server, typically available at:

https://{instance-root}/id

For example, the Identity Server for the testdb instance is: https://testdb.my.erp.net/id

You can discover this automatically through the system's discovery endpoint (see below).

Discovering the Identity Server

Every ERP.net instance exposes an auto-discovery endpoint that lists all available sites and services - including the Identity Server, Domain API, and other functional components.

This allows developers (and tools) to dynamically determine where to send authentication and API requests.

Request:

GET https://{instance-root}/sys/auto-discovery

GET https://testdb.my.erp.net/sys/auto-discovery

Response (truncated):

{
  "WebSites": [
    {
      "Type": "ID",
      "Status": "Working",
      "Url": "https://testdb.my.erp.net/id"
    },
    {
      "Type": "DomainAPI",
      "Status": "Working",
      "Url": "https://testdb.my.erp.net/api",
      "AdditionalProperties": {
        "ODataServiceRoot": "https://testdb.my.erp.net/api/domain/odata/"
      }
    }
  ]
}

This tells you that the instance's Identity Server is active at /id, and that the Domain API is available at /api.

Standard endpoints

The Identity Server exposes the standard OAuth 2.0 and OpenID Connect endpoints. The most commonly used ones are:

1) Discovery endpoint

The discovery endpoint provides metadata about the Identity Server - including its issuer name, supported scopes, signing keys, and the exact URLs for authentication, token exchange, and logout.

This information helps client libraries and apps automatically configure themselves without hardcoding endpoints.

Request:

GET https://{instance-root}/id/.well-known/openid-configuration

GET https://testdb.my.erp.net/id/.well-known/openid-configuration

Example response (truncated):

{
  "issuer": "https://testdb.my.erp.net/id",
  "authorization_endpoint": "https://testdb.my.erp.net/id/connect/authorize",
  "token_endpoint": "https://testdb.my.erp.net/id/connect/token",
  "end_session_endpoint": "https://testdb.my.erp.net/id/connect/endsession",
  "jwks_uri": "https://testdb.my.erp.net/id/.well-known/openid-configuration/jwks",
  "response_types_supported": [
    "code",
    "token",
    "id_token",
    "code id_token"
  ],
  "grant_types_supported": [
    "authorization_code",
    "client_credentials",
    "refresh_token"
  ],
  "scopes_supported": [
    "openid",
    "profile",
    "offline_access",
    "update"
  ]
}

Key properties:

  • issuer - The base URL identifying the Identity Server. Used to validate tokens issued by this instance.
  • authorization_endpoint - The URL where interactive user logins begin (used in the Authorization Code flow).
  • token_endpoint - The URL used by apps to exchange authorization codes or client credentials for access tokens.
  • end_session_endpoint - The logout URL used to terminate user sessions and trigger single sign-out.
  • jwks_uri - Location of the public signing keys used to validate tokens issued by this Identity Server.
  • grant_types_supported - Lists which OAuth 2.0 grant types (flows) are available.
  • scopes_supported - Lists available permission scopes that can be requested in tokens.
Note

The discovery document is automatically generated by each instance's Identity Server and always reflects its current configuration. Applications should use it dynamically rather than hardcoding endpoints.

Note

Client libraries typically fetch this automatically to configure themselves.

2) Authorize endpoint

Starts an interactive sign-in and authorization request. Used by apps that act on behalf of a user (Authorization Code flow).

GET https://{instance-root}/id/connect/authorize

Example request:

GET https://testdb.my.erp.net/id/connect/authorize?
  client_id=MyApp&
  redirect_uri=https%3A%2F%2Fmyapp.com%2Fcallback&
  response_type=code&
  scope=openid%20profile%20offline_access&
  state=xyz123

After successful sign-in, the browser is redirected to redirect_uri with an code parameter that the app will exchange for tokens.

3) Token endpoint

Exchanges an authorization code or client credentials for access tokens (and refresh tokens where applicable).

POST https://{instance-root}/id/connect/token

Example: exchange authorization code:

POST /id/connect/token
Content-Type: application/x-www-form-urlencoded

client_id=MyApp&
client_secret=secret&
grant_type=authorization_code&
code=abc123&
redirect_uri=https%3A%2F%2Fmyapp.com%2Fcallback

Example response: exchange authorization code:

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "df9834jf...",
  "scope": "openid profile offline_access"
}

Example: client credentials:

POST /id/connect/token
Content-Type: application/x-www-form-urlencoded

client_id=MyServiceApp&
client_secret=secret&
grant_type=client_credentials&
scope=update

Example response: client credentials:

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read update"
}
Note

Refresh tokens are issued only for suitable interactive confidential clients using Authorization Code flow. They are not issued for Client Credentials.

4) End session endpoint

Triggers logout and single sign-out across participating apps.

GET https://{instance-root}/id/connect/endsession

Example: end session:

GET https://testdb.my.erp.net/id/connect/endsession?
  id_token_hint=eyJhbGciOi...&
  post_logout_redirect_uri=https%3A%2F%2Fmyapp.com%2Flogout-complete

Internal and external users

The Identity Server can authenticate both:

  • Internal users - Licensed users who can open sessions and access instance data through APIs. Internal users can obtain access tokens for Domain API and Table API, depending on scopes and permissions.

  • External users - Community or customer users who can authenticate but typically cannot access data APIs directly. For these users, the Identity Server issues identity tokens for sign-in to external-facing apps (for example, portals), but not API-access tokens for Domain API or Table API.

Typical flows at a glance

  • Authorization Code - Interactive apps acting on behalf of a signed-in user. The app redirects to the Identity Server, gets a code, exchanges it for tokens.

  • Client Credentials - Service or background apps acting as themselves. The app directly requests a token from the Identity Server using its client credentials.

  • Reference tokens (API keys: PAT/SAT) - Opaque, manually issued tokens that represent long-lived delegated access. They are looked up by the instance on each request.

Quick reference

Purpose Path Used for
Discovery /.well-known/openid-configuration Fetch metadata and endpoint locations
Authorize /connect/authorize Start user sign-in and obtain an authorization code
Token /connect/token Exchange code or credentials for tokens
End session /connect/endsession Log out and propagate single sign-out

All paths are relative to https://{instance-root}/id.

Learn More

Suggest improvement to this page