Authorize access to APIs in your API center

You can configure settings to authorize access to APIs in your API center. These settings:

• Enable API authentication using either API keys or OAuth 2.0 authorization
• Associate specific authentication methods with specific API versions in your inventory
• Manage authentication to API versions by designated users or groups through access policies
• Enable authorized users to test APIs directly in the API Center portal

Prerequisites

• An API center in your Azure subscription. If you haven't created one already, see Quickstart: Create your API center.

• Register at least one API in your API center. For more information, see Tutorial: Register APIs in your API inventory.

• Configure an environment and a deployment for the API. For more information, see Tutorial: Add environments and deployments for APIs.

• Set up the API Center portal. For more information, see Set up API Center portal.

• An Azure key vault to store API keys or OAuth 2.0 client secrets. For steps to create a key vault, see Create a Key Vault. The key vault should use the Azure role-based access control (RBAC) permission model.

• (For OAuth 2.0 authorization using Microsoft Entra ID) Permissions to create an app registration in a Microsoft Entra tenant associated with your Azure subscription.

Option 1: Configure settings for API key authentication

For an API that supports API key authentication, follow these steps to configure settings in your API center.

1. Store API key in Azure Key Vault

To manage the API key securely, store it in Azure Key Vault, and access the key vault using your API center's managed identity.

To store the API key as a secret in the key vault, see Set and retrieve secret in Key Vault.

Enable a managed identity in your API center

For this scenario, your API center uses a managed identity to access the key vault. Depending on your needs, enable either a system-assigned or one or more user-assigned managed identities.

The following example shows how to enable a system-assigned managed identity by using the Azure portal. At a high level, configuration steps are similar for a user-assigned managed identity.

1. In the portal, navigate to your API center.
2. In the left menu, under Security, select Managed identities.
3. Select System assigned, and set the status to On.
4. Select Save.

Assign the Key Vault Secrets User role to the managed identity

Assign your API center's managed identity the Key Vault Secrets User role in your key vault. The following steps use the Azure portal.

1. In the portal, navigate to your key vault.
2. In the left menu, select Access control (IAM).
3. Select + Add role assignment.
4. On the Add role assignment page, set the values as follows:
   1. On the Role tab, select Key Vault Secrets User.
   2. On the Members tab, in Assign access to, select Managed identity > + Select members.
   3. On the Select managed identities page, select the system-assigned managed identity of your API center that you added in the previous section. Click Select.
   4. Select Review + assign twice.

2. Add API key configuration in your API center

1. In the portal, navigate to your API center.

2. In the left menu, under Governance, select Authorization (preview) > + Add configuration.

3. In the Add configuration page, set the values as follows:

   Setting	Description
   Title	A name for the authorization.
   Description	Optional description for the authorization.
   Security scheme	Select API Key.
   API key location	How the key is presented in API requests. Available values are Header (request header) and Query (query parameter).
   API key parameter name	Name of the HTTP header or query parameter that contains the API key. Example: x-api-key
   API key Key Vault secret reference	Secret identifier of the API key in Azure Key Vault. Example: https://<key-vault-name>.vault.azure.net/secrets/<secret-name>/<version>

4. Select Create.

Option 2: Configure settings for OAuth 2.0 authorization

For an API that supports OAuth 2.0 authorization, follow these steps to configure authentication settings in your API center. You can configure settings for one or both of the following OAuth 2.0 authorization flows:

• Authorization code flow with PKCE (Proof Key for Code Exchange) - This flow is recommended for authenticating users in the browser, such as in the API Center portal.
• Client credentials flow - This flow is recommended for applications that don't require a specific user's permissions to access data.

1. Create an OAuth 2.0 app

For OAuth 2.0 authorization, create an app registration in an identity provider, such as the Microsoft Entra tenant associated with your Azure subscription. The exact creation steps depend on the identity provider you use.

The following example shows how to create an app registration in Microsoft Entra ID.

1. Sign in to the Azure portal with an account with sufficient permissions in the tenant.
2. Navigate to Microsoft Entra ID > + New registration.
3. In the Register an application page, enter your application registration settings:
   1. In Name, enter a meaningful name for the app.
   2. In Supported account types, select an option that suits your scenario, for example, Accounts in this organizational directory only (Single tenant).
   3. (For authorization code flow) In Redirect URI, select Single-page application (SPA) and set the URI. Enter the URI of your API Center portal deployment, in the following form: https://<service-name>.portal.<location>.azure-api-center.ms. Replace <service name> and <location> with the name of your API center and the location where it's deployed, Example: https://myapicenter.portal.eastus.azure-api-center.ms
   4. Select Register.
4. In the left menu, under Manage, select Certificates & secrets, and then select + New client secret.
   1. Enter a Description.
   2. Select an option for Expires.
   3. Select Add.
   4. Copy the client secret's Value before leaving the page. You will need it in the following section.
5. Optionally, add API scopes in your app registration. For more information, see Configure an application to expose a web API.

When you configure OAuth 2.0 authorization in your API center, you will need the following values from the app registration:

• The Application (client) ID from the app registration's Overview page, and the Client secret you copied previously.
• The following endpoint URLs on the app registration's Overview > Endpoints page:
  • OAuth2.0 authorization endpoint (v2) - the authorization endpoint for Microsoft Entra ID
  • OAuth 2.0 token endpoint (v2) - the token endpoint and token refresh endpoint for Microsoft Entra ID
• Any API scopes configured in the app registration.

2. Store client secret in Azure Key Vault

To manage the secret securely, store it in Azure Key Vault, and access the key vault using your API center's managed identity.

To store the API key as a secret in the key vault, see Set and retrieve secret in Key Vault.

Enable a managed identity in your API center

For this scenario, your API center uses a managed identity to access the key vault. Depending on your needs, enable either a system-assigned or one or more user-assigned managed identities.

The following example shows how to enable a system-assigned managed identity by using the Azure portal. At a high level, configuration steps are similar for a user-assigned managed identity.

1. In the portal, navigate to your API center.
2. In the left menu, under Security, select Managed identities.
3. Select System assigned, and set the status to On.
4. Select Save.

Assign the Key Vault Secrets User role to the managed identity

Assign your API center's managed identity the Key Vault Secrets User role in your key vault. The following steps use the Azure portal.

1. In the portal, navigate to your key vault.
2. In the left menu, select Access control (IAM).
3. Select + Add role assignment.
4. On the Add role assignment page, set the values as follows:
   1. On the Role tab, select Key Vault Secrets User.
   2. On the Members tab, in Assign access to, select Managed identity > + Select members.
   3. On the Select managed identities page, select the system-assigned managed identity of your API center that you added in the previous section. Click Select.
   4. Select Review + assign twice.

3. Add OAuth 2.0 authorization in your API center

1. In the portal, navigate to your API center.

2. In the left menu, under Governance, select Authorization (preview) > + Add configuration.

3. In the Add configuration page, set the values as follows:

   

   Note

   Configure settings based on the app registration you created previously in your identity provider. If you're using Microsoft Entra ID, find the Client ID on the Overview page of the app registration, and find the URL endpoints on the Overview > Endpoints page.

   Setting	Description
   Title	A name for the authorization.
   Description	Optional description for the authorization.
   Security scheme	Select OAuth2.
   Client ID	Client ID (GUID) of the app that you created in your identity provider.
   Client secret	Secret identifier of the client secret in Azure Key Vault. Example: https://<key-vault-name>.vault.azure.net/secrets/<secret-name>/<version>
   Authorization URL	OAuth 2.0 authorization endpoint for the identity provider. Example for Microsoft Entra ID: https://login.microsoftonline.com/<tenant>/oauth2/v2.0/authorize
   Token URL	OAuth 2.0 token endpoint for the identity provider. Example for Microsoft Entra ID: https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token
   Refresh URL	OAuth 2.0 token refresh endpoint for the identity provider. For most providers, same as the Token URL Example for Microsoft Entra ID: https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token
   OAuth2 flow	One or both of the OAuth 2.0 flows that you want to use. Available values are Authorization code (PKCE) and Client credentials.
   Scopes	One or more API scopes configured for your API, separated by spaces. If no scopes are configured, enter .default.

4. Select Create to save the configuration.

Add authentication configuration to an API version

After configuring settings for an API key or an OAuth 2.0 flow, add the API key or OAuth 2.0 configuration to an API version in your API center.

1. In the portal, navigate to your API center.
2. In the left menu, under Assets, select APIs.
3. Select an API that you want to associate the authorization configuration with.
4. In the left menu, under Details, select Versions.
5. Select the API version that you want to add the authentication configuration to.
6. In the left menu, under Details, select Manage Access (preview) > + Add authentication.
7. In the Add authentication page, select an available Authentication configuration that you want to associate.
8. Select Create.

Manage access by specific users or groups

You can manage access by specific users or groups in your organization to an API version's authentication configuration. You do this by configuring an access policy that assigns users or groups the API Center Credential Access Reader role, scoped to specific authentication configurations in the API version. This is useful, for example, if you want to allow only specific users to test an API in the API Center portal using an API key or OAuth 2.0 flow.

1. In the portal, navigate to your API center.

2. Navigate to an API version to which you've added an authentication configuration (see previous section).

3. In the left menu, under Details, select Manage Access (preview).

4. Select the Edit access policies dropdown at the end of the row for the authentication configuration whose access you want to manage.

5. In the Manage access page, select + Add > Users or + Add > Groups.

6. Search for and select the users (or groups) that you want to add. You can select multiple items.

7. Click Select.

Test API in API Center portal

You can use the API Center portal to test an API that you configured for authentication and user access.

1. In the portal, navigate to your API center.

2. In the left menu, under API Center Portal, select Portal settings.

3. Select View API Center portal.

4. In the API Center portal, select an API that you want to test.

5. Select a version of the API that has an authentication method configured.

6. Under Options, select View documentation.

7. Select an operation in the API, and select Try this API.

8. In the window that opens, review the authentication settings. If you have access to the API, select Send to try the API.

9. If the operation is successful, you see the 200 OK response code and the response body. If the operation fails, you see an error message.

Related content

• Set up API Center portal
• Enable the Azure API Center portal view in Visual Studio Code
• Authentication and authorization to APIs in Azure API Management