---
title: Authentication to an Activate API using OAuth through Azure
slug: authentication-to-an-activate-api-using-oauth-through-azure
docTags: 
createdAt: 2025-07-25T03:50:58.711Z
---



### Setup Activate application in Azure

This document assumes the Activate application in Azure has already been setup, if not refer to [Activate Azure App Quick Start Guide](docId\:DvlDwFrmW9StjonbQslT6) 

## Register Client Application

Login to your organisation’s Azure portal and select Manage Entra ID

1. Click **App registrations**
2. Click **New Registration, **enter the following values
   1. **Name** = “ACME Test Client”, enter your client name, we will use “ACME Test Client” as an example in this document.
   2. **Supported account types** = “Accounts in this organizational directory only (\<your domain> only - Single tenant)”
   3. Redirect URI can be left blank
   4. Click **Register** button&#x20;
3. Copy the Application (client) ID for later



## Create Secret for Client Application

The client will use this to acquire a token which it will send to the Activate API for authentication.

1. Navigate back to App Registrations and select the previously created ACME Test Client application.
2. Select Certificates & secrets from the left
3. Click **New client secret**
4. Enter values
   1. **Description** = Description of the secret
   2. Select an appropriate **Expires&#x20;**&#x76;alue
5. Click **Add**
6. Copy the value of the new secret, this will be used by the Client application to obtain an access token. This should be treated like a password and only shared with appropriate parties.



## Configure App Role



1. In Azure Portal access the **Enterprise Applications** list
2. Select the Activate application (name may differ in your environment)
3. Click the **Properties** menu option on the left
4. If **Assignment required?&#x20;**&#x4F;ption is set to **Yes** proceed to step #5, if set to **No** then proceed to API Permissions section.
5. Navigate back to **App registrations** and the Activate application.
6. Select the **App roles** menu option
7. Click **Create app role**
8. Enter values
   1. **Display Name** = “Activate Custom API Access”
   2. **Allowed Member Types** = “Applications”
   3. **Value** = “Activate.Custom.API.Access”
   4. **Description** = “Role to allow access to Activate Custom APIs”
   5. **Do you want to enable this app role?** = Checked
9. Click **Apply**

## API Permissions



1. Navigate to **App Registrations**
2. Select your **Client&#x20;**&#x61;pplication. This is the app that will be connecting to the API.
3. Select menu option **API Permissions**
4. Assign Activate Custom API Access role, only required if Assignment required is turned on as per previous section
   1. Click **Add a permission**
   2. Click tab **My APIs**
5. Click Activate application. If the application is not available in the **My APIs** tab, try the **APIs my organization uses**
6. Check **Activate.Custom.API.Access** from the Activate permissions list
7. Click **Add permissions** button
8. Add User.Read permission to allow application to read its profile
   1. Click **Add a permission**
   2. Select **Microsoft Graph**
9. Select **Delegated permissions**
10. Enter “User.Read” into the search
11. Drop down **User**
12. Check **User.Read, Sign in and read user profile.**
13. Click **Add permissions** button
14. Click **Grant admin consent for \<domain>**
15. Confirm admin consent



## Other configuration

In order to get the correct token content, the version of the token must be explicitly configured in the application manifest.

1. Navigate to the Activate app registration
2. Click the **Manifest** option on the left
3. Change **accessTokenAcceptedVersion** to “2” if it isn’t set to that already.
4. Click **Save**

## Setup Activate API

1. Create a UserReference parameter named **OAuth\::**\<*application ID of Client application in Azure*> on the Activate Custom API. This authorises the application to access the API in Activate. Point the user to an Activate API User role member or user with Execute/Read security rights on the API resource.&#x20;
2. Set Authentication = OAuth



## Client Example

This is an Activate script which can be used to test the connection to the Activate API, acting as the client.

```csharp
//@import System.Net.Http
//@import Microsoft.Identity.Client

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Threading.Tasks;

using Innovation.Activate;
using Microsoft.Identity.Client;

class Script : ScriptBase
{
    string URL = "<full path to API here>";
    string appSecret = "<test client secret here>";
    string tenantName = "<tenant name here>";
    string appID = "<client app ID here>";

    ConfidentialClientApplication application;

    public void main()
    {
        // Get Activate application, this forms the scope of the access token request
        string scope = $"api://{Evaluator.GetString("=//Resources/ActiveDirectory/External Directories/Azure/ApplicationID")}/.default";

        HttpClient http = GetHttpClient(new List<string> { scope });

        Trace.WriteLine("Logged in");

        HttpRequestMessage m = new HttpRequestMessage(HttpMethod.Get, URL);
        HttpResponseMessage r = http.SendAsync(m).Result;

        Trace.WriteLine(string.Format("{0}: {1}", r.StatusCode.ToString(), r.ReasonPhrase));
        Trace.WriteLine(string.Format("[{0}]", r.Content.ReadAsStringAsync().Result));
    }

    // Get an authenticated Microsoft Graph Service client.
    public HttpClient GetHttpClient(List<string> scopes)
    {
        HttpClient httpClient = new HttpClient();

        string accessToken = Task.Run<string>(() =>
        {
            return GetAppAccessTokenAsync(scopes);
        }).Result;

        // Append the access token to the request.
        httpClient.DefaultRequestHeaders.Add(
            "Authorization",
            string.Format("Bearer {0}", accessToken)
        );

        return httpClient;
    }

    // Get an access token. First tries to get the token from the token cache.
    public async Task<string> GetAppAccessTokenAsync(List<string> scopes)
    {
        // wrong token version is being returned
        string authority = string.Format(
            @"https://login.microsoftonline.com/{0}/oauth/V2.0/authorize",
            tenantName
        );

        var application =
            ConfidentialClientApplicationBuilder
                .Create(appID)
                .WithAuthority(AzureCloudInstance.AzurePublic, tenantName)
                .WithClientSecret(appSecret)
                .Build();

        AuthenticationResult result =
            await application.AcquireTokenForClient(scopes).ExecuteAsync();

        return result.AccessToken;
    }
}

```

# Troubleshooting

| **HTTP Code**<br />         | **Possible Cause**                                                                                                                          |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| 403 - Forbidden             | Execute API rights to user not configured                                                                                                   |
| 401 - Unauthorized          | Token has not been validated, check TenantID is configured on //Resources/External Directories/Azure, this is used to determine the issuer. |
| 500 - Internal Server Error | OAuth\::\<apiKey> not configured                                                                                                            |