App-Only Token Login — Integration Guide
How it works
Your service Microsoft Entra Ejento AI
──────────── ─────────────── ─────────
1. Request a token ─────────► issues an app-only token
2. Send that token ──────────────────────────────────────────► checks the token, and checks
your app is registered in
Service Clients
3. Receive ◄────────────────────────────────────────── an Ejento AI access token
4. Call Ejento AI APIs with the Ejento AI access tokenBefore you start
| # | Step | Who |
|---|---|---|
| 1 | Register the application in Ejento AI under Service Clients | Your Global Admin |
| 2 | Exchange the app-only token with Ejento AI | Your service, at runtime |
| 3 | Call Ejento AI APIs with the Ejento AI access token | Your service |
1. Register your application in Ejento AI
Calling application is not authorized.Choose the service account email first
[email protected].Adding a service client (steps a Global Admin needs to perform)
1.
2.
3.
| Field | Required | What to enter |
|---|---|---|
| Name | Yes | A label you will recognise later, e.g. Transcript Service. |
| Application (Client) ID | Yes | Your application's Application (client) ID. |
| Tenant ID | No, but recommended | Your application's Directory (tenant) ID. When set, tokens from any other tenant are refused. Ejento AI checks with Microsoft that the tenant exists. |
| Service account email | Yes | The new address chosen above. |
4.
Errors when registering
| Message | What to do |
|---|---|
'<email>' is an existing user. Use a dedicated service address. | Choose an address that is not already an Ejento AI user. |
'<value>' is not a valid Directory (tenant) ID. Expected a GUID, as shown on the app registration's Overview page. | Copy the Directory (tenant) ID from the app's Overview page in Entra. |
Tenant '<id>' was not found in Microsoft Entra. Check the Directory (tenant) ID on the app registration. | The ID is well formed but no such tenant exists. Check for a typo. |
This app_id is already registered with service_email '<email>'. One app_id maps to exactly one service account. | The application already acts as another account. Use that account, or a different application. |
This app_id is already registered with a different tenant_id. ... | Use the same Tenant ID as the existing registration for that application. |
A service client with this app_id and service_email is already registered in this organization | It is already registered. Edit or restore the existing one. |
Checking that it works
Revoking and restoring a client
403 Calling application is not authorized. A revoked client can be restored. Clients cannot be deleted.2. Exchange the token with Ejento AI
Authorization header, because the token in the body is the credential. No email is sent. Ejento AI identifies your application from the token and looks up the account you registered for it in section 1.{
"success": true,
"message": "Login successful",
"data": {
"access_token": "eyxxxxxx...",
"ejento_access_token": "aaaaaaaa-bbbbbb-cccc-ddddd-eeeeeee",
"token_type": "bearer"
}
}Calling Ejento AI APIs
ejento_access_token to call the Ejento AI APIs, sent as Authorization: Bearer <ejento_access_token>. The access_token is for the Ejento AI auth service itself, for example the refresh call below. The Ejento AI APIs do not accept it.Token lifetime and refresh
access_token expires 7 days after it is issued, so refresh before then, at least once every 6 days:access_token and ejento_access_token. Replace both stored values. Full details are in Authentication and token refresh.3. What Ejento AI checks
| Check | Requirement |
|---|---|
| Signature | Signed by Microsoft. Verified against Microsoft's public keys, so it cannot be forged. |
Issuer (iss) | A Microsoft Entra tenant. v1 and v2 tokens are both accepted. |
| App-only | No scp claim. A token from a user sign-in is refused. |
Application (appid / azp) | Matches an active client in Service Clients. |
Tenant (tid) | Matches the client's Tenant ID, if one is set. |
Audience (aud) | Matches the audience your token was requested for. |
api://<guid> and the bare <guid>, are accepted, so the token version does not matter.4. Error reference
{"success": false, "message": "Request Failed",
"data": {"error": {"code": "HTTP_401", "details": "<message>"}}}A 503 means Microsoft could not be reached. It is never a bad token.
| Status | Message | Meaning | What to do |
|---|---|---|---|
| 401 | Invalid Azure AD token: Audience doesn't match | The token was requested for a different audience | Request the token for the audience in Which token to request |
| 401 | Invalid Azure AD token: ... | Bad signature, malformed token or unknown signing key | Check you are sending the token exactly as Microsoft returned it |
| 401 | Azure AD token has expired | The token is past its expiry | Request a new token |
| 401 | Token issuer is not a valid Microsoft tenant | The token was not issued by Microsoft Entra | Request it from login.microsoftonline.com |
| 401 | Expected an app-only token, but a delegated user token was provided | The token came from a user sign-in | Use the app-only flow in Getting an App-Only Token |
| 401 | Token does not identify a calling application | The token has no application ID | Use the app-only flow in Getting an App-Only Token |
| 401 | Token tenant does not match the registered client | The token's tenant differs from the client's Tenant ID | Check the Tenant ID on the client |
| 403 | Calling application is not authorized | No active client for this application | Check the client exists, is active, and its Application ID matches your app |
| 403 | Service user does not exist. Register the service client first. | The account behind the client could not be found | Contact Ejento AI |
| 403 | App-only token login is currently disabled | This sign-in method is off for your deployment | Contact Ejento AI |
| 503 | Could not reach Microsoft to verify the token signature | Microsoft is temporarily unreachable | Retry with backoff |