{
  "aid": "mitel.io:main-2017-09-01",
  "name": "platform-api-admin-token",
  "type": "Index",
  "description": "A loosely [OAuth 2.0](https://tools.ietf.org/html/rfc6749) compliant authentication service used to obtain bearer tokens for use with the CloudLink Platform micro-service APIs.\n\n# Endpoints\n- /token is for [OAuth 2.0](https://tools.ietf.org/html/rfc6749) grants.\n- /assume-role/token can be used to switch account or role (subject to permissions) for a logged in user or client.\n- /guest/token can be used to obtain an anonymous user access token with limited access rights (guest level access).\n- /authorize can be used by a registered client application to initiate an [Authorization Code Grant](https://tools.ietf.org/html/rfc6749#section-4.1) authorization flow.\n- /policy-test can be used to test a set of resources against a user's access policy.\n- /applications can be used to manage the application registry.\n- /credentials is an internal API that can be used to perform actions on stored credentials.\n- /.well-known/jwks is the JSON Web Key Set endpoint for an account.\n- /trusted-issuers is used to configure the trusted token issuers for an account.\n# Supported OAuth 2.0 grants\n- password - [Resource Owner Password Credentials Flow](https://tools.ietf.org/html/rfc6749#section-4.3)\n- client_credentials - [Client Credentials Flow](https://tools.ietf.org/html/rfc6749#section-4.4)\n- refresh_token - [Refreshing an Access Token](https://tools.ietf.org/html/rfc6749#page-47)\n- authorization_code - [Authorization Code Grant](https://tools.ietf.org/html/rfc6749#section-4.1)\n- urn:ietf:params:oauth:grant-type:token-exchange - [OAuth 2.0 Token Exchange](https://tools.ietf.org/html/rfc8693) - For Zoom clients\n\nInput arguments may be passed either as `application/x-www-form-urlencoded` pairs in the request body and/or in a basic auth header.\n# OAuth 2.0 Grants\nOAuth 2.0 requests are handled by the `/token` endpoint.\n## Login using username and password\nDuring user login, the platform checks that the user and account are active and that the password is valid.\n\nThe username identifies the user, it is matched against the user's `userId`, `uniqueUserId`, `email`, `mobile` or `loginId` properties.\n\nExample:\n\n`grant_type=password&username=jsmith%40somecompany.com&password=****`\n\nIf the request is successful the response is `201 (Created)` and access/refresh tokens are returned.  If the username or password are incorrect then the response is `401 (Unauthorized)`.\n## Login using username, password and account ID\nIf the `/token` endpoint returns 409 (Conflict) the username may be present in more than one account.  Provide the account ID to select which account to log the user into:\n\n`grant_type=password&username=jsmith%40somecompany.com&password=****&account_id=4321`\n\nIf the request is successful the response is `201 (Created)` and access/refresh tokens are returned.  If the username or password are incorrect then the response is `401 (Unauthorized)`.\n## Refresh token to obtain fresh tokens\nAccess tokens are valid for (by default) 1 hour, the platform also returns a fresh token which is valid for (by default) 14 days and can be used to obtain fresh access and refresh tokens.  During refresh, the platform checks that the account and user are still active.\n\n`grant_type=refresh_token&refresh_token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`\n\nIf the request is successful the response is `201 (Created)` and access/refresh tokens are returned.  If the token is not valid then the response is `401 (Unauthorized)`.  If the user or account is not active then the response is `403 (Forbidden)`.\n## Client login using client ID and secret\nDuring client login, the platform checks that the client and account are active and that the client secret is valid.\n\n`grant_type=client_credentials&client_id=9552c9497d624b75a7399fdb494abb1e&client_secret=******`\n\nIf the request is successful the response is `201 (Created)` and access/refresh tokens are returned.  If the client ID or secret are incorrect then the response is `401 (Unauthorized)`.\n## Client login with basic auth header\nClients in possession of a client password MAY use the HTTP Basic authentication scheme as defined in [RFC2617](https://tools.ietf.org/html/rfc6749#section-2.3.1) to authenticate with the authorization server.  The client identifier is encoded using the `application/x-www-form-urlencoded` encoding algorithm, and the encoded value is used as the username; the client password is encoded using the same algorithm and used as the password.\n\nheader:\n\n`Authorization: 'Basic bXfecHB1UTIyNA=='`\n\nbody:\n\n`grant_type=client_credentials`\n\nIf the encoded username and password are valid and the request is successful then the response is `201 (Created)` and access/refresh tokens are returned.  If the username or password are invalid then the response is `401 (Unauthorized)`.\n\n# Authorization Code Grant Flow\nAuthorization is initiated using the `/authorize` endpooint.  In order to use this route, the application must be registered in the platform and a client ID created for the application.  Also any redirect URL(s) which are valid for the application need to be pre-registered.\n\nThe application wishing to log in a user and obtain a user token begins by redirecting the user agent (browser) to an authentication portal such as the Mitel global auth portal, providing client ID, response type, redirect URI, state and application name:\n\n```\n  HTTP 1.1 302 Found\n  https://auth.mitel.io/authorize?\n  client_id=bca4584614724174b8290bdd6c7d5967\n  &response_type=code\n  &redirect_uri=https://some.app.mitel.io\n  &state=abc\n  &app_name=SomeApp\n```\n\nThe authentication portal will ask the user for thier username, password and possibly thier account ID if the username is present in multiple accounts.  It will then initiate Oauth authorization by sending a POST request to the /authorize endpoint with the following parameters:\n\n- client_id is the pre-registered client ID for the application.\n- response_type: code is the only currently supported response type.\n- username will be used to identify the user.\n- password is the user's password.\n- account_id can be provided if the platform returns 409 (Conflict) because the username exists in more that one account.\n- redirect_uri is the URI to re-direct the user agent to, after successful login.\n\nThe platform then logs the user in by generating access and refresh tokens, they are stored ready to be retrieved by the application and an authorization code is returned to the auth portal, to pass along to the calling application.\n\nDuring user login, the platform checks that the user and account are active and that the password is valid.\n\nThe username identifies the user, it is matched against the user's `userId`, `uniqueUserId`, `email`, `mobile` or `loginId` properties.\n\nExample (posted to /authorize):\n\n`client_id=bc81084614724174b8290bdd6c7d5967&response_type=code&username=jsmith%40somecompany.com&password=****&account_id=1234&redirect_uri=https%3A%2F%2Faccounts.dev.mitel.io`\n\nThe application will then send the auth code to the `/token` endpoint using the authorization_code flow.\n\nExample (posted to /token):\n\n`grant_type=authorization_code&client_id=bc81084614724174b8290bdd6c7d5967&code=d09fea34-d053-4b80-9bdc-f7d0ffd3b2bd&scope=abc`\n\nNote that auth codes are only stored in the auth service for a period of time.   If the application waits too long, the auth code may have expired.\n\nIf the request is successful the response is `201 (Created)` and access/refresh tokens are returned.  If the code is not valid or has expired then the response is `401 (Unauthorized)`.  If the user or account is not active then the response is `403 (Forbidden)`.\n# Assume Role Feature\nIt is often useful for a partner administrator to switch accounts, to one of the accounts that they administer, as an account administrator, or for an account administrator to assume a user role to limit the effect of unintended requests.  The platform provides an authenticated route for this purpose, served by the `/assume-role/token` endpoint.\n\nA logged in administrator can use this route to issue a token in a different account or with a lower role (depending on thier permissions).\n\nA logged in client can use this route to issue an anonymous user token in a different account or with a lower role (depending on thier permissions).\n\n## Administrator assuming a user role in a different account\nExample:\n\n```\n{\n    \"accountId\": \"1234\",\n  \"role\": \"USER\"\n}\n```\n\n## Guest Access\nGuest access allows an unauthenticated client to obtain access to an account with extremely limited usage rights.  Guest access must be explicitly enabled by turning on an account policy.  The client simply provides a guest principal ID (which can be anything, a generated UUID would be a good choice) and the name of the user to the `/guest/token` route.\n\nExample:\n\n```\n{\n    \"principalId\": \"7688c81e-c6ea-4777-a1a2-8163ed318a19\",\n  \"accountId\": \"1234\",\n  \"name\": \"Guest User One\"\n}\n```\n\nIf the request is successful the response is `201 (Created)` and access/refresh tokens are returned.  If the account is not active, if the principal ID identifies a legitimate platform user or the account is not enabled with the guest access policy then the response is `403 (Forbidden)` (user impersonation is not allowed by any route).",
  "url": "https://raw.githubusercontent.com/jentic/jentic-public-apis/refs/heads/main/apis/openapi/mitel.io/main/2017-09-01/apis.json",
  "tags": [
    "mitel.io",
    "main"
  ],
  "created": "2026-04-11",
  "modified": "2026-04-11",
  "specificationVersion": "0.19",
  "access": "3rd-Party",
  "maintainers": [
    {
      "FN": "Jentic",
      "X-github": "jentic",
      "url": "https://github.com/jentic"
    }
  ],
  "apis": [
    {
      "aid": "mitel.io:main-2017-09-01",
      "name": "platform-api-admin-token",
      "description": "A loosely [OAuth 2.0](https://tools.ietf.org/html/rfc6749) compliant authentication service used to obtain bearer tokens for use with the CloudLink Platform micro-service APIs.\n\n# Endpoints\n- /token is for [OAuth 2.0](https://tools.ietf.org/html/rfc6749) grants.\n- /assume-role/token can be used to switch account or role (subject to permissions) for a logged in user or client.\n- /guest/token can be used to obtain an anonymous user access token with limited access rights (guest level access).\n- /authorize can be used by a registered client application to initiate an [Authorization Code Grant](https://tools.ietf.org/html/rfc6749#section-4.1) authorization flow.\n- /policy-test can be used to test a set of resources against a user's access policy.\n- /applications can be used to manage the application registry.\n- /credentials is an internal API that can be used to perform actions on stored credentials.\n- /.well-known/jwks is the JSON Web Key Set endpoint for an account.\n- /trusted-issuers is used to configure the trusted token issuers for an account.\n# Supported OAuth 2.0 grants\n- password - [Resource Owner Password Credentials Flow](https://tools.ietf.org/html/rfc6749#section-4.3)\n- client_credentials - [Client Credentials Flow](https://tools.ietf.org/html/rfc6749#section-4.4)\n- refresh_token - [Refreshing an Access Token](https://tools.ietf.org/html/rfc6749#page-47)\n- authorization_code - [Authorization Code Grant](https://tools.ietf.org/html/rfc6749#section-4.1)\n- urn:ietf:params:oauth:grant-type:token-exchange - [OAuth 2.0 Token Exchange](https://tools.ietf.org/html/rfc8693) - For Zoom clients\n\nInput arguments may be passed either as `application/x-www-form-urlencoded` pairs in the request body and/or in a basic auth header.\n# OAuth 2.0 Grants\nOAuth 2.0 requests are handled by the `/token` endpoint.\n## Login using username and password\nDuring user login, the platform checks that the user and account are active and that the password is valid.\n\nThe username identifies the user, it is matched against the user's `userId`, `uniqueUserId`, `email`, `mobile` or `loginId` properties.\n\nExample:\n\n`grant_type=password&username=jsmith%40somecompany.com&password=****`\n\nIf the request is successful the response is `201 (Created)` and access/refresh tokens are returned.  If the username or password are incorrect then the response is `401 (Unauthorized)`.\n## Login using username, password and account ID\nIf the `/token` endpoint returns 409 (Conflict) the username may be present in more than one account.  Provide the account ID to select which account to log the user into:\n\n`grant_type=password&username=jsmith%40somecompany.com&password=****&account_id=4321`\n\nIf the request is successful the response is `201 (Created)` and access/refresh tokens are returned.  If the username or password are incorrect then the response is `401 (Unauthorized)`.\n## Refresh token to obtain fresh tokens\nAccess tokens are valid for (by default) 1 hour, the platform also returns a fresh token which is valid for (by default) 14 days and can be used to obtain fresh access and refresh tokens.  During refresh, the platform checks that the account and user are still active.\n\n`grant_type=refresh_token&refresh_token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`\n\nIf the request is successful the response is `201 (Created)` and access/refresh tokens are returned.  If the token is not valid then the response is `401 (Unauthorized)`.  If the user or account is not active then the response is `403 (Forbidden)`.\n## Client login using client ID and secret\nDuring client login, the platform checks that the client and account are active and that the client secret is valid.\n\n`grant_type=client_credentials&client_id=9552c9497d624b75a7399fdb494abb1e&client_secret=******`\n\nIf the request is successful the response is `201 (Created)` and access/refresh tokens are returned.  If the client ID or secret are incorrect then the response is `401 (Unauthorized)`.\n## Client login with basic auth header\nClients in possession of a client password MAY use the HTTP Basic authentication scheme as defined in [RFC2617](https://tools.ietf.org/html/rfc6749#section-2.3.1) to authenticate with the authorization server.  The client identifier is encoded using the `application/x-www-form-urlencoded` encoding algorithm, and the encoded value is used as the username; the client password is encoded using the same algorithm and used as the password.\n\nheader:\n\n`Authorization: 'Basic bXfecHB1UTIyNA=='`\n\nbody:\n\n`grant_type=client_credentials`\n\nIf the encoded username and password are valid and the request is successful then the response is `201 (Created)` and access/refresh tokens are returned.  If the username or password are invalid then the response is `401 (Unauthorized)`.\n\n# Authorization Code Grant Flow\nAuthorization is initiated using the `/authorize` endpooint.  In order to use this route, the application must be registered in the platform and a client ID created for the application.  Also any redirect URL(s) which are valid for the application need to be pre-registered.\n\nThe application wishing to log in a user and obtain a user token begins by redirecting the user agent (browser) to an authentication portal such as the Mitel global auth portal, providing client ID, response type, redirect URI, state and application name:\n\n```\n  HTTP 1.1 302 Found\n  https://auth.mitel.io/authorize?\n  client_id=bca4584614724174b8290bdd6c7d5967\n  &response_type=code\n  &redirect_uri=https://some.app.mitel.io\n  &state=abc\n  &app_name=SomeApp\n```\n\nThe authentication portal will ask the user for thier username, password and possibly thier account ID if the username is present in multiple accounts.  It will then initiate Oauth authorization by sending a POST request to the /authorize endpoint with the following parameters:\n\n- client_id is the pre-registered client ID for the application.\n- response_type: code is the only currently supported response type.\n- username will be used to identify the user.\n- password is the user's password.\n- account_id can be provided if the platform returns 409 (Conflict) because the username exists in more that one account.\n- redirect_uri is the URI to re-direct the user agent to, after successful login.\n\nThe platform then logs the user in by generating access and refresh tokens, they are stored ready to be retrieved by the application and an authorization code is returned to the auth portal, to pass along to the calling application.\n\nDuring user login, the platform checks that the user and account are active and that the password is valid.\n\nThe username identifies the user, it is matched against the user's `userId`, `uniqueUserId`, `email`, `mobile` or `loginId` properties.\n\nExample (posted to /authorize):\n\n`client_id=bc81084614724174b8290bdd6c7d5967&response_type=code&username=jsmith%40somecompany.com&password=****&account_id=1234&redirect_uri=https%3A%2F%2Faccounts.dev.mitel.io`\n\nThe application will then send the auth code to the `/token` endpoint using the authorization_code flow.\n\nExample (posted to /token):\n\n`grant_type=authorization_code&client_id=bc81084614724174b8290bdd6c7d5967&code=d09fea34-d053-4b80-9bdc-f7d0ffd3b2bd&scope=abc`\n\nNote that auth codes are only stored in the auth service for a period of time.   If the application waits too long, the auth code may have expired.\n\nIf the request is successful the response is `201 (Created)` and access/refresh tokens are returned.  If the code is not valid or has expired then the response is `401 (Unauthorized)`.  If the user or account is not active then the response is `403 (Forbidden)`.\n# Assume Role Feature\nIt is often useful for a partner administrator to switch accounts, to one of the accounts that they administer, as an account administrator, or for an account administrator to assume a user role to limit the effect of unintended requests.  The platform provides an authenticated route for this purpose, served by the `/assume-role/token` endpoint.\n\nA logged in administrator can use this route to issue a token in a different account or with a lower role (depending on thier permissions).\n\nA logged in client can use this route to issue an anonymous user token in a different account or with a lower role (depending on thier permissions).\n\n## Administrator assuming a user role in a different account\nExample:\n\n```\n{\n    \"accountId\": \"1234\",\n  \"role\": \"USER\"\n}\n```\n\n## Guest Access\nGuest access allows an unauthenticated client to obtain access to an account with extremely limited usage rights.  Guest access must be explicitly enabled by turning on an account policy.  The client simply provides a guest principal ID (which can be anything, a generated UUID would be a good choice) and the name of the user to the `/guest/token` route.\n\nExample:\n\n```\n{\n    \"principalId\": \"7688c81e-c6ea-4777-a1a2-8163ed318a19\",\n  \"accountId\": \"1234\",\n  \"name\": \"Guest User One\"\n}\n```\n\nIf the request is successful the response is `201 (Created)` and access/refresh tokens are returned.  If the account is not active, if the principal ID identifies a legitimate platform user or the account is not enabled with the guest access policy then the response is `403 (Forbidden)` (user impersonation is not allowed by any route).",
      "image": "",
      "baseURL": "https://authentication.api.mitel.io/2017-09-01",
      "humanURL": "https://github.com/jentic/jentic-public-apis/tree/main/apis/openapi/mitel.io/main/2017-09-01",
      "version": "2017-09-01",
      "tags": [
        "mitel.io",
        "main"
      ],
      "properties": [
        {
          "type": "OpenAPI",
          "name": "OpenAPI definition",
          "url": "https://raw.githubusercontent.com/jentic/jentic-public-apis/refs/heads/main/apis/openapi/mitel.io/main/2017-09-01/openapi.json",
          "mediaType": "application/openapi+json"
        },
        {
          "type": "GitHubRepo",
          "url": "https://github.com/jentic/jentic-public-apis/tree/main/apis/openapi/mitel.io/main/2017-09-01"
        }
      ],
      "contact": [
        {
          "FN": "CloudLink support",
          "email": "cloudlink.support@mitel.io",
          "url": "https://mitel.io/support"
        }
      ]
    }
  ]
}