Skip to content

authorize-api-access.md

Latest commit

 

History

History
243 lines (163 loc) · 16.6 KB

authorize-api-access.md

File metadata and controls

243 lines (163 loc) · 16.6 KB
title Configure API access in Azure API Center
description Configure access to APIs in your Azure API Center inventory using API keys, OAuth 2.0 authorization, or other HTTP security schemes. Authorized users can test APIs in the API Center portal.
ms.service azure-api-center
ms.topic how-to
ms.date 03/10/2026
ms.custom

Authorize access to APIs in your API center

Configure settings to authorize access to APIs in your API center. These settings:

  • Enable API authentication and authorization using API keys, OAuth 2.0 authorization, or another HTTP security scheme
  • Associate authentication configurations with API versions in your inventory
  • Manage access to API versions for designated users or groups through access policies
  • Enable authorized users to test APIs in the API Center portal

Note

This feature is currently in preview.

Prerequisites

Option 1: Configure API key authentication

For an API that supports API key authentication, complete the following steps.

1. Store API key in Azure Key Vault

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

Access the key vault using your API center's managed identity.

Enable a managed identity in your API center

[!INCLUDE enable-managed-identity]

Assign the managed identity the Key Vault Secrets User role

[!INCLUDE configure-managed-identity-kv-secret-user]

2. Add API key configuration

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

  2. Under Governance, select Authorization (preview) > + Add configuration.

  3. On the Add configuration page, set the following values: :::image type="content" source="media/authorize-api-access/configure-api-key.png" alt-text="Screenshot of configuring an API key in the portal.":::

    Setting Description
    Title Enter a name for the authorization.
    Description Optionally, enter a description for the authorization.
    Security scheme Select API Key.
    API key location Select how the key is presented in API requests. Available values are Header (request header) and Query (query parameter).
    API key parameter name Enter the name of the HTTP header or query parameter that contains the API key. Example: x-api-key
    API key Key Vault secret reference Select Select and select the subscription, key vault, and secret that you stored. Example: https://<key-vault-name>.vault.azure.net/secrets/<secret-name>

  4. Select Create.

After completing this configuration, go to the Add authentication configuration to an API version section to associate the API key configuration with an API version.

Option 2: Configure OAuth 2.0 authorization

For an API that supports OAuth 2.0 authorization, complete the following steps. You can configure one or both of the following flows:

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

1. Create an OAuth 2.0 app

Create an app registration in an identity provider, such as the Microsoft Entra tenant associated with your subscription. The steps depend on your identity provider.

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

  1. Sign in to the Azure portal with sufficient permissions in the tenant.
  2. Go to Microsoft Entra ID > + New registration.
  3. On the Register an application page:
    1. In Name, enter a meaningful name.
    2. In Supported account types, select an appropriate option, for example, Accounts in this organizational directory only (Single tenant).
    3. (For authorization code flow) In Redirect URI, select Single-page application (SPA) and enter the URI of your API Center portal: https://<service-name>.portal.<location>.azure-api-center.ms. Replace <service-name> and <location> with your API center name and deployment location. Example: https://myapicenter.portal.eastus.azure-api-center.ms
    4. Select Register.
  4. Under Manage, select Certificates & secrets > + New client secret.
    1. Enter a Description.
    2. Select an option for Expires.
    3. Select Add.
    4. Copy the client secret Value before leaving the page. You need it in the next section.
  5. Optionally, add API scopes in your app registration. See Configure an application to expose a web API.

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

  • Application (client) ID from the Overview page, and the Client secret you copied.
  • The following endpoint URLs from Overview > Endpoints:
    • OAuth2.0 authorization endpoint (v2)
    • OAuth 2.0 token endpoint (v2) (also used as the token refresh endpoint)
  • Any API scopes you configured.

2. Store client secret in Azure Key Vault

To store the client secret in the key vault, see Set and retrieve secret in Key Vault.

Access the key vault using your API center's managed identity.

Enable a managed identity in your API center

[!INCLUDE enable-managed-identity]

Assign the managed identity the Key Vault Secrets User role

[!INCLUDE configure-managed-identity-kv-secret-user]

3. Add OAuth 2.0 configuration

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

  2. Under Governance, select Authorization (preview) > + Add configuration.

  3. On the Add configuration page, set the following values:

    :::image type="content" source="media/authorize-api-access/configure-oauth.png" lightbox="media/authorize-api-access/configure-oauth.png" alt-text="Screenshot of configuring OAuth 2.0 in the portal.":::

    [!NOTE] Use values from the app registration you created previously. For Microsoft Entra ID, find the Client ID on the app registration Overview page, and URL endpoints on Overview > Endpoints.

    Setting Description
    Title Enter a name for the authorization.
    Description Optionally, enter a description for the authorization.
    Security scheme Select OAuth2.
    Client ID Enter the client ID (GUID) of the app you created in your identity provider.
    Client secret Select the subscription, key vault, and client secret that you stored.

    Example: https://<key-vault-name>.vault.azure.net/secrets/<secret-name>
    Authorization URL Enter the 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 Enter the 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 Enter the 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 Select one or both OAuth 2.0 flows: Authorization code (PKCE) and Client credentials.
    Scopes Enter 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.

After completing this configuration, go to the Add authentication configuration to an API version section to associate the OAuth 2.0 configuration with an API version.

Option 3: Configure settings for another HTTP security scheme

For APIs that use another HTTP security scheme, such as Basic authentication or bearer tokens that don't use OAuth 2.0, complete the following steps. You might need to choose this option for legacy APIs.

In the portal, go to your API center.

  1. Under Governance, select Authorization (preview) > + Add configuration.

  2. On the Add configuration page, set the following values:

    Setting Description
    Title Enter a name for the authorization.
    Description Optionally, enter a description for the authorization.
    Security scheme Select HTTP.
    Authentication scheme Select the authentication scheme used by the API. Examples include the schemes in the following table.
    Authentication scheme Description
    Basic Sends username:password as a Base64-encoded string in the Authorization: Basic <credentials> header.
    Bearer Sends a token other than an OAuth 2.0 access token in the Authorization: Bearer <token> header.
    Digest A challenge-response mechanism where the server sends a nonce; the client responds with a hash of credentials + nonce.
    Custom Another mechanism scheme such as a vendor-specific scheme.

After completing this configuration, go to the next section to associate the configuration with an API version.

Add authentication configuration to an API version

After configuring an authentication scheme, associate the configuration with an API version.

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

  2. Under Inventory, select Assets.

  3. Select the API to associate the configuration with.

  4. Under Details, select Versions, then select the target API version.

  5. In the context menu for the API version, select Manage Access (preview). :::image type="content" source="media/authorize-api-access/add-authentication-to-version.png" alt-text="Screenshot of associating an authentication configuration with an API version in the portal.":::

  6. On the Manage Access page, select + Add authentication.

  7. Select an available Authentication configuration.

  8. Select Create.

Note

You can add multiple authentication configurations to an API version (for example, both API key and OAuth 2.0), if supported by the API. You can also add the same configuration to multiple API versions.

Manage access for specific users or groups

Configure an access policy that assigns users or groups the API Center Credential Access Reader role, scoped to specific authentication configurations in an API version. This role allows only designated users to test an API in the API Center portal.

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

  2. Go to an API version with an authentication configuration.

  3. Select Manage Access (preview).

  4. Select an authentication configuration you want to manage.

  5. In the dropdown menu, select Edit access policies. :::image type="content" source="media/authorize-api-access/edit-access-policies.png" alt-text="Screenshot of adding an access policy in the portal.":::

  6. On the Manage access page, select + Add > Users or + Add > Groups.

  7. Search for and select users or groups. You can select multiple items.

  8. Select Select.

Tip

To remove users or groups, select Delete in the context menu on the Manage access page.

Test the API in API Center portal

Test an API that you configured for authentication and user access.

Tip

You can also configure visibility settings to control which APIs appear for all signed-in users in the portal.

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

  2. Under API Center Portal, select Portal settings > View API Center portal.

  3. Select an API, then select a version with an authentication method configured.

  4. Under Options, select View documentation. :::image type="content" source="media/authorize-api-access/view-api-documentation-small.png" lightbox="media/authorize-api-access/view-api-documentation.png" alt-text="Screenshot of API details in API Center portal.":::

  5. Select an operation, then select Try this API.

  6. Review the authentication settings. If you have access, select Send. :::image type="content" source="media/authorize-api-access/test-api-operation-small.png" lightbox="media/authorize-api-access/test-api-operation.png" alt-text="Screenshot of testing an API in the API Center portal's test console.":::

  7. A successful operation returns a 200 OK response code and response body. A failed operation returns an error message.

Related content