A shallow dive into AWS Identity Store API (and other AWS APIs)

A StackOverflow question asked how to list the users in the AWS Identity Store using Postman. They tried to call the API in a similar way to calling AWS IAM APIs, but it didn't work. Since I was already working with Identity Center, I saw this as an opportunity to dive deeper into how it works and decided to give it a shot.

This indeed turned out to be an interesting exercise. The documentation covered operations and request parameters well, but it lacked concrete examples and didn't provide an endpoint URL for the Identity Store, unlike IAM (see this for example). That's what made it interesting.

So I found Nick Frichette's blog post on A Look at AWS API Protocols. Nick doesn't cover the Identity Center or Identity Store API, but he explains how AWS API requests are structured based on different protocols in his blog. As he points out in the blog, all of this can be found in the AWS SDK codebases. That was my starting point to understand how <insert-a-service> API works — with the help of AWS SDKs!

AWS SDKs

AWS SDKs are one of the best places to start when exploring how AWS APIs work, although, technically, the API reference/docs should probably come first.

AWS SDKs come in different flavors: Python, Go, JavaScript, etc. I chose to look at Botocore — which sits under the hood of Boto3 (Python SDK) and the AWS CLI — to understand how the Identity Center API works.

Botocore - Identity Store API

I'll use the Identity Store API as an example to show how you can find the information you need to call an AWS API in <any-http-client>.

Here's a summary from my SO answer:

Summary

To list users from AWS IAM Identity Center, you need to use the region-specific Identity Store API URL. This is different from how you list users in IAM.

Unlike IAM, it uses POST request with a JSON body and the request syntax looks like this (assuming you have set the authorization headers for AWS correctly, e.g. for Postman, or directly go to the AWS docs for information on signing API requests: Signing AWS API requests.):

Request syntax:

POST / HTTP/1.1
Host: identitystore.${identity_center_region}.amazonaws.com
Content-Type: application/x-amz-json-1.1
X-Amz-Target: AWSIdentityStore.ListUsers
Authorization: AWS4-HMAC-SHA256 Credential=ASIAEXAMPLEEXAMPLEEX/20250319/${identity_center_region}/identitystore/aws4_request, SignedHeaders=content-type;host;x-amz-content-sha256;x-amz-date;x-amz-security-token;x-amz-target, Signature=...
 
{
  "IdentityStoreId": "${identity_store_id}"
}

Replace ${identity_center_region} with the region corresponding to your Identity Store ID (e.g. us-east-1) and replace ${identity_store_id} with the Identity Store ID (e.g. d-1234567890).

How do you find this?

To construct an API request for Identity Store, you can refer to the following lines/snippets from Botocore's codebase:

1. For endpoint URL

The Identity Store API's endpoint URL is defined in Botocore's endpoint rule set:

"endpoint": {
    "url": "https://identitystore.{Region}.amazonaws.com",  
    "properties": {},
    "headers": {}
},

2. For request headers

You can check the serialization logic for JSON for the expected request headers:

serialized['headers'] = {
    'X-Amz-Target': target,
    'Content-Type': f'application/x-amz-json-{json_version}',
}

3. For request format

The service definition file provides metadata about the request format and operation:

"metadata": {
    "apiVersion": "2020-06-15",
    "endpointPrefix": "identitystore",  
    "jsonVersion": "1.1",   
    "protocol": "json", 
    "serviceAbbreviation": "IdentityStore",
    "serviceFullName": "AWS SSO Identity Store",
    "serviceId": "identitystore",
    "signatureVersion": "v4",   
    "signingName": "identitystore",
    "targetPrefix": "AWSIdentityStore",  
    "uid": "identitystore-2020-06-15"
},

The ListUsers operation is defined with its HTTP method and path:

"ListUsers": {
    "name": "ListUsers",
    "http": {
        "method": "POST",
        "requestUri": "/"
    }
}

So here's how we derive the request headers in this case:

Content-Type: ${protocol}-${jsonVersion}
X-Amz-Target: ${targetPrefix}.${operations.name}

Substitute the placeholders with the values:

Content-Type: application/x-amz-json-1.1
X-Amz-Target: AWSIdentityStore.ListUsers

Combine all the pieces and you have everything needed to construct the final request in <any-http-client>. Here's an example using Postman: