Calling an API from another API

How do you, as a developer, ensure Zero Trust when you have one API that needs to call another API? In this article, you'll learn how to securely develop your application when it's working on behalf of a user.

When a user drives an app's UI, the app might use a delegated permission so that the API knows which user on whose behalf the app is working. It would inspect the subject (sub) claim or object ID (oid) and tenant ID (tid) claims in the access token that the app provides when calling the API. The API wouldn't rely on the untrusted app, which is just a call coming from somewhere on the network. Instead, it would validate the token to ensure that the API only works on behalf of the app user that Microsoft Entra ID verified.

When one API (we'll refer to it as the Original API) calls another, it's vital that the API that we're calling (we'll refer to it as the Downstream API) follows the above-described validation process. The Downstream API can't rely on an untrusted network source. It must get the user identity from a properly validated access token.

If the Downstream API doesn't follow the proper validation process, the Downstream API must rely on the Original API to provide the identity of the user in another way. The Downstream API might incorrectly use an application permission to perform the operation. Then the Original API would become the sole authority over which users could achieve which results against the Downstream API. The Original API could intentionally (or unintentionally) allow a user to accomplish a task that the user couldn't otherwise accomplish. For example, one user could change the details of another user or read and update documents that the user doesn't have permission to access. Improper validation can cause serious security issues.

For better security, the Original API acquires a delegated permission access token to provide to the Downstream API when the Original API makes the call. Let's walk through how this works.

Client App acquires access token to call Original API

The following diagram shows the Client App on the left and the Original API on the right.

Diagram shows Client App with ID and access tokens on the left and the Original API that requires authorization on the right.

The Client Application has acquired a delegated permission access token (indicated by the pentagon shape with the "A" label) to the Original API. The delegated permission access token allows it to work on behalf of the user to call the Original API that requires authorization.

Client App gives access token to Original API

The animation below shows the Client App giving the access token to the Original API. The Original API fully validates and inspects the access token to determine the identity of the Client App's user.

Animated diagram shows Client App on the left giving an access token to the Original API that requires authorization on the right.

The animated diagram shows two diagrams with a motion transition between the first diagram and the second diagram. First diagram title: The Client App acquired an access token to call the Original API. First diagram subtitle: The Client Application has an access 'A' token that allows it to work on behalf of user identified in token to call the Original API. First diagram components: A representation of a cloud appears in the top center of the slide enclosing a Microsoft Entra ID icon. On the lower left, a rectangle shape represents the Client App. Below the Client App rectangle are two hexagons shapes labeled 'ID' and 'A' that represent ID and access tokens. On the lower right, a cube-shaped icon, a cloud shape, and a world icon represent the Original API. To its left, a square shape label is 'Authorization Required.' An arrow connects the shapes on the left to the shapes on the right. Second diagram title: The Client App gives the access token to the Original API. Second diagram components: A representation of a cloud appears in the top center of the slide enclosing a Microsoft Entra ID icon. On the lower left, a rectangle shape represents the Client App. Below the Client App rectangle is a hexagon shape labeled 'ID' that represents an ID token. On the lower right, a cube-shaped icon, a cloud shape, and a world icon represent the Original API. To its left, a square shape label is 'Authorization Required.' To its left is a hexagon shape labeled 'A' that represents an access token. An arrow connects the shapes on the left to the shapes on the right.

Original API performs token validation and enforcement

The next animation shows that, after the Client App gives the access token to the Original API, the Original API performs token validation and enforcement. If all is good, the API will proceed and service the request for the Client App.

Animated diagram shows Client App with ID token on the left giving the access token to the Original API on the right.

The animated diagram shows two diagrams with a motion transition between the first diagram and the second diagram. First diagram title: The Client App gives the access token to the Original API. First diagram components: A representation of a cloud appears in the top center of the slide enclosing a Microsoft Entra ID icon. On the lower left, a rectangle shape represents the Client App. Below the Client App rectangle is a hexagon shape labeled 'ID' that represents an ID token. On the lower right, a cube-shaped icon, a cloud shape, and a world icon represent the Original API. To its left, a square shape label is 'Authorization Required.' On its left is a hexagon shape labeled 'A' that represents an access token. An arrow connects the shapes on the left to the shapes on the right. Second diagram title: The Original API performs token validation and enforcement. If all good, the API proceeds and services the request. Second diagram components: A representation of a cloud appears in the top center of the slide enclosing a Microsoft Entra ID icon. On the lower left, a rectangle shape represents the Client App. Below the Client App rectangle is a hexagon shape labeled 'ID' that represents an ID token. On the lower right, a cube-shaped icon, a cloud shape, and a world icon represent the Original API. An arrow connects the shapes on the left to the shapes on the right. Above the arrow, to the right and below the cloud shape, is a hexagon shape labeled 'A' that represents an access token.

Original API can't use access token to call Downstream API

The following animation shows that the Original API now wants to call a Downstream API. However, the Original API can't use the access token to call the Downstream API.

Animated diagram shows Client App giving access token to Original API. Authorization Required prevents Original API from giving token to Downstream API.

The animated diagram shows two diagrams with a motion transition between the first diagram and the second diagram. First diagram title: The Original API wants to call a Downstream API. First diagram components: A representation of a cloud appears in the top center of the slide enclosing a Microsoft Entra ID icon. On the lower left, a rectangle shape represents the Client App. Below the Client App rectangle is a hexagon shape labeled 'ID' that represents an ID token. In the lower middle, a cube-shaped icon, a cloud shape, and a world icon represent the Original API. An arrow connects the shapes on the left to the shapes in the middle. Above the arrow, to the left and below the cloud shape, is a hexagon shape labeled 'A' that represents an access token. Second diagram title: The Original API can't use the token to call the Downstream API. Second diagram components: A representation of a cloud appears in the top center of the slide enclosing a Microsoft Entra ID icon. On the lower left, a rectangle shape represents the Client App. Below the Client App rectangle is a hexagon shape labeled 'ID' that represents an ID token. In the lower middle, a cube-shaped icon, a cloud shape, and a world icon represent the Original API. An arrow connects the shapes on the left to the shapes in the middle. Above the arrow, to the left and below the cloud shape, is a hexagon shape labeled 'A' that represents an access token. On the lower right, a cube-shaped icon, a cloud shape, and a world icon represent the Downstream API. To its left, a square shape label is 'Authorization Required.' An arrow connects the shapes in the middle to the shapes on the right.

Original API goes back to Microsoft Entra ID

In the animation below, the Original API needs to go back to Microsoft Entra ID. It needs an access token to call the Downstream API on behalf of the user.

Animated diagram shows Client App giving access token to Original API that needs validation from Microsoft Entra ID to call Downstream API.

The animated diagram shows two diagrams with a motion transition between the first diagram and the second diagram. First diagram title: The Original API can't use the token to call the Downstream API. First diagram components: A representation of a cloud appears in the top center of the slide enclosing a Microsoft Entra ID icon. On the lower left, a rectangle shape represents the Client App. Below the Client App rectangle is a hexagon shape labeled 'ID' that represents an ID token. In the lower middle, a cube-shaped icon, a cloud shape, and a world icon represent the Original API. An arrow connects the shapes on the left to the shapes in the middle. Above the arrow, to the left and below the cloud shape, is a hexagon shape labeled 'A' that represents an access token. On the lower right, a cube-shaped icon, a cloud shape, and a world icon represent the Downstream API. To its left, a square shape label is 'Authorization Required.' An arrow connects the shapes in the middle to the shapes on the right. Second diagram title: Original API goes back to Microsoft Entra ID. Second diagram subtitle: Needs an access token to call the Downstream API on behalf of the user. Second diagram components: A representation of a cloud appears in the top center of the slide enclosing a Microsoft Entra ID icon. On the lower left, a rectangle shape represents the Client App. Below the Client App rectangle is a hexagon shape labeled 'ID' that represents an ID token. In the lower middle, a cube-shaped icon, a cloud shape, and a world icon represent the Original API. An arrow connects the shapes on the left to the shapes in the middle. Above the arrow, to the left and below the cloud shape, is a hexagon shape labeled 'A' that represents an access token. Above the Original API shapes, an arrow connects them to the Microsoft Entra cloud shape. On the lower right, a cube-shaped icon, a cloud shape, and a world icon represent the Downstream API. To its left, a square shape label is 'Authorization Required.' An arrow connects the shapes in the middle to the shapes on the right.

The next animation shows the Original API providing the token that the Original API received from the Client App and the Original API's client credentials.

Animated diagram shows Client App giving access token to Original API that receives validation from Microsoft Entra ID to call Downstream API.

The animated diagram shows two diagrams with a motion transition between the first diagram and the second diagram. First diagram title: Original API goes back to Microsoft Entra ID. First diagram subtitle: Needs an access token to call the Downstream API on behalf of the user. First diagram components: A representation of a cloud appears in the top center of the slide enclosing a Microsoft Entra ID icon. On the lower left, a rectangle shape represents the Client App. Below the Client App rectangle is a hexagon shape labeled 'ID' that represents an ID token. In the lower middle, a cube-shaped icon, a cloud shape, and a world icon represent the Original API. An arrow connects the shapes on the left to the shapes in the middle. Above the arrow, to the left and below the cloud shape, is a hexagon shape labeled 'A' that represents an access token. Above the Original API shapes, an arrow connects them to the Microsoft Entra cloud shape. On the lower right, a cube-shaped icon, a cloud shape, and a world icon represent the Downstream API. To its left, a square shape label is 'Authorization Required.' An arrow connects the shapes in the middle to the shapes on the right. Second diagram title: Original API goes back to Microsoft Entra ID. Second diagram subtitle: Provides the token from the Client App and the credentials for the Original API. Second diagram components: A representation of a cloud appears in the top center of the slide enclosing a Microsoft Entra ID icon. On the lower left, a rectangle shape represents the Client App. Below the Client App rectangle is a hexagon shape labeled 'ID' that represents an ID token. In the lower middle, a cube-shaped icon, a cloud shape, and a world icon represent the Original API. An arrow connects the shapes on the left to the shapes in the middle. Above the Original API shapes, an arrow connects them to the Microsoft Entra cloud shape. To the left of that arrow, to the left and below the cloud shape, is a hexagon shape labeled 'A' that represents an access token. Below the access token is a key shape. On the lower right, a cube-shaped icon, a cloud shape, and a world icon represent the Downstream API. To its left, a square shape label is 'Authorization Required.' An arrow connects the shapes in the middle to the shapes on the right.

Microsoft Entra ID will check for things like consent or conditional access enforcement. You may have to go back to your calling client and provide a reason for not being able to get the token. You would typically use a claims challenge process to go back to the calling application with information regarding consent not being received (such as being related to conditional access policies).

Microsoft Entra ID performs checks

In the following animation, Microsoft Entra ID performs its checks. If everything is okay, Microsoft Entra ID will issue an access token to the Original API to call the Downstream API on behalf of the user.

Animated diagram shows Original API giving access token to Downstream API after validating with Microsoft Entra ID.

The animated diagram shows two diagrams with a motion transition between the first diagram and the second diagram. First diagram title: Original API goes back to Microsoft Entra ID. First diagram subtitle: Provides the token from the Client App and the credentials for the Original API. First diagram components: A representation of a cloud appears in the top center of the slide enclosing a Microsoft Entra ID icon. On the lower left, a rectangle shape represents the Client App. Below the Client App rectangle is a hexagon shape labeled 'ID' that represents an ID token. In the lower middle, a cube-shaped icon, a cloud shape, and a world icon represent the Original API. An arrow connects the shapes on the left to the shapes in the middle. Above the Original API shapes, an arrow connects them to the Microsoft Entra cloud shape. To the left of that arrow, to the left and below the cloud shape, is a hexagon shape labeled 'A' that represents an access token. Below the access token is a key shape. On the lower right, a cube-shaped icon, a cloud shape, and a world icon represent the Downstream API. To its left, a square shape label is 'Authorization Required.' An arrow connects the shapes in the middle to the shapes on the right. Second diagram title: Microsoft Entra ID checks conditional access, consent, etc. Second diagram subtitle: The Original API receives its own access token to call the Downstream API on behalf of the user who signed into the Client App. Second diagram components: A representation of a cloud appears in the top center of the slide enclosing a Microsoft Entra ID icon. On the lower left, a rectangle shape represents the Client App. Below the Client App rectangle is a hexagon shape labeled 'ID' that represents an ID token. In the lower middle, a cube-shaped icon, a cloud shape, and a world icon represent the Original API. An arrow connects the shapes on the left to the shapes in the middle. Above the Original API shapes, an arrow connects them to the Microsoft Entra cloud shape. On the lower right, a cube-shaped icon, a cloud shape, and a world icon represent the Downstream API. To its left, a square shape label is 'Authorization Required.' An arrow connects the shapes in the middle to the shapes on the right. Above that arrow, to the right of the Original API shapes, is a hexagon shape labeled 'A' that represents an access token.

Original API has user context with On-Behalf-Of flow

The animation below illustrates the On-Behalf-Of flow (OBO) process that allows an API to continue to have the user context as it calls Downstream API.

Animated diagram shows Original API giving access token to Downstream API.

The animated diagram shows two diagrams with a motion transition between the first diagram and the second diagram. First diagram title: On-Behalf-Of flow process allows the Original API to continue to have user context as it calls the Downstream API. First diagram components: On the lower left, a rectangle shape represents the Client App. Below the Client App rectangle is a hexagon shape labeled 'ID' that represents an ID token. In the lower middle, a cube-shaped icon, a cloud shape, and a world icon represent the Original API. An arrow connects the shapes on the left to the shapes in the middle. On the lower right, a cube-shaped icon, a cloud shape, and a world icon represent the Downstream API. To its left, a square shape label is 'Authorization Required.' An arrow connects the shapes in the middle to the shapes on the right. Above that arrow, to the right of the Original API shapes, is a hexagon shape labeled 'A' that represents an access token. Second diagram title: On-Behalf-Of flow process allows the Original API to continue to have user context as it calls the Downstream API. Second diagram components: On the lower left, a cube-shaped icon, a cloud shape, and a world icon represent the Original API. On the lower right, a cube-shaped icon, a cloud shape, and a world icon represent the Downstream API. To its left, a square shape label is 'Authorization Required.' An arrow connects the shapes on the left to the shapes on the right. Above that arrow, to the right of the Original API shapes, is a hexagon shape labeled 'A' that represents an access token.

Original API calls Downstream API

In the next animation, we call the Downstream API. The token that the Downstream API receives will have the proper audience (aud) claim that indicates the Downstream API.

Animated diagram shows Downstream API validating access token from Original API.

The token will include the scopes for granted consent and the original app user identity. The Downstream API can properly implement effective permissions to ensure that the identified user has permission to accomplish the requested task. You'll want to use the on behalf of flow to acquire tokens for an API to call another API to make sure that user context passes to all Downstream APIs.

Best option: Original API performs On-Behalf-Of flow

This last animation shows that the best option is for the Original API to perform On-Behalf-Of flow (OBO). If the Downstream API receives the correct token, it will be able to correctly respond.

Animated diagram shows Downstream API receiving access token from Original API.

When an API is acting on behalf of a user and needs to call another API, the API must use OBO to acquire a delegated permission access token to call the Downstream API on behalf of the user. APIs should never use application permissions to call Downstream APIs when the API is acting on behalf of a user.

Next steps