canonical: https://jentic.com/apis/amazonaws.com/aws-sso # AWS Single Sign-On Jentic publishes the only available OpenAPI specification for AWS Single Sign-On, keeping it validated and agent-ready. AWS IAM Identity Center (formerly AWS Single Sign-On) Portal is the runtime that lets users and tools list the AWS accounts and roles assigned to them and exchange a bearer token for short-lived sigv4 credentials. Agents can list accessible accounts, list roles within an account, fetch role credentials for use with other AWS APIs, and log out the current session. The four endpoints model the sign-in portal's read flow only - administration of permission sets and assignments is handled through the sso-admin API. ## For AI agents Exchange an IAM Identity Center bearer token for AWS account roles and short-lived credentials. Agents can list accounts, list roles, get role credentials, and log out. ## Scope Does not manage permission sets, account assignments, or user directories - use only for runtime account and role discovery and federation credential exchange. ## Capabilities - List the AWS accounts the current bearer token has access to with ListAccounts - List the IAM roles assigned to a specific account via ListAccountRoles - Exchange a bearer token plus account and role for sigv4 credentials with GetRoleCredentials - Invalidate the current portal session with the Logout operation ## Use cases ### Programmatic Federation from CLI or Custom Tooling Tools that need temporary AWS credentials for IAM Identity Center users follow this flow: the user authenticates via the OIDC device flow (sso-oidc), the tool receives a bearer token, and then ListAccountRoles and GetRoleCredentials yield the AccessKeyId, SecretAccessKey, SessionToken needed to call other AWS APIs. The Logout operation revokes the active session. Example prompt: Call ListAccounts with the bearer token, then ListAccountRoles for a chosen accountId, then GetRoleCredentials for roleName='ReadOnlyAccess' to obtain AccessKeyId, SecretAccessKey, and SessionToken. ### Account and Role Discovery for Federated Users Internal portals that surface 'which AWS environments can I access?' use ListAccounts and ListAccountRoles against the user's bearer token. The portal renders a list of (account, role) tuples and lets the user pick one to federate into, then calls GetRoleCredentials. Example prompt: ListAccounts with the bearer token, then for the first account ListAccountRoles to display all assigned roles to the user. ### Session Termination on Logout When a user signs out of an internal tool, the application calls the SSO Logout operation with the bearer token to revoke the session at IAM Identity Center. Subsequent calls with that token then return Unauthorized. Example prompt: Call the Logout operation with the active x-amz-sso_bearer_token header to revoke the user's portal session. ### AI Agent Multi-Account Access via Jentic AI agents using Jentic that operate across many AWS accounts can call SSO through Jentic to fetch fresh role credentials per account on demand. Through Jentic, the bearer token is held in the vault and short-lived credentials are produced inside Jentic - never exposed to the agent's prompt. Example prompt: Search Jentic for 'get role credentials from aws sso', execute GetRoleCredentials for accountId and roleName, and use the returned RoleCredentials to call other AWS APIs through Jentic. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | /assignment/accounts#x-amz-sso_bearer_token | List AWS accounts assigned to the bearer token (ListAccounts) | | GET | /assignment/roles#x-amz-sso_bearer_token&account_id | List roles assigned in a specific account (ListAccountRoles) | | GET | /federation/credentials#role_name&account_id&x-amz-sso_bearer_token | Get short-lived role credentials (GetRoleCredentials) | | POST | /logout#x-amz-sso_bearer_token | Invalidate the current portal session (Logout) | ## Key resources - **Accounts** — AWS accounts assigned to the current bearer token; ListAccounts - **Account Roles** — Roles available in a specific account; ListAccountRoles - **Role Credentials** — Short-lived sigv4 credentials for a (role, account) pair; GetRoleCredentials - **Session** — The current bearer-token session; Logout ## Why Jentic - **Setup:** Wiring AWS Single Sign-On by hand means computing SigV4 signatures, picking the right regional portal.sso host, and carrying the bearer token through each call yourself. Through Jentic you install once, import Single Sign-On from the API Directory, store the token once, and your agent calls it. - **Permission scoping:** Single Sign-On passes the bearer token and account id as request parameters rather than resource ids in the path, so scope the agent to the operations it needs, such as listing accounts and roles. You choose the operations it may call, so credential exchange or logout are not included unless you add them. - **Credential handling:** Your IAM Identity Center bearer token is stored once, encrypted, by your own Jentic One instance and injected into each SSO Portal call at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'list AWS accounts assigned to me' or 'get role credentials for an account', and Jentic returns the matching Single Sign-On operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **AWS SSO OIDC** — OIDC device flow that issues the bearer token consumed by the SSO Portal - **AWS Single Sign-On Admin** — Administrative API for permission sets and account assignments - **AWS Security Token Service** — AssumeRole-based federation for IAM principals; used when IAM Identity Center is not in scope ## FAQ ### Why is there no official OpenAPI spec for AWS Single Sign-On? AWS does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call AWS Single Sign-On via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the AWS Single Sign-On use? The SSO Portal accepts an IAM Identity Center bearer access token in the x-amz-sso_bearer_token header. The token is obtained from the sso-oidc CreateToken endpoint after completing the OAuth 2.0 device authorisation flow. Through Jentic, the token is stored in the vault and injected into each request server-side. ### Can I exchange the bearer token for AWS API credentials? Yes. GetRoleCredentials at /federation/credentials returns an AccessKeyId, SecretAccessKey, SessionToken, and expiration for the chosen (account_id, role_name) pair. Those credentials can then sign requests to any other AWS API. ### What are the rate limits for the AWS Single Sign-On? The SSO Portal applies standard AWS throttling - typical limits are a few requests per second per token for List operations and a slightly higher cap for GetRoleCredentials. Throttled calls return TooManyRequestsException; retry with exponential backoff. ### How do I list every account a user can access through Jentic? Through Jentic, search for 'list aws sso accounts', load the ListAccounts schema, and execute with the bearer token managed in the vault. Jentic returns the accountList array containing accountId, accountName, and emailAddress for each assigned account. ### Is AWS Single Sign-On free? IAM Identity Center is offered at no additional charge - you pay only for the underlying AWS resources accessed via the federated roles. SSO connections to external SaaS applications are also included. ### Can I limit what my agent is allowed to do with the AWS Single Sign-On API? Yes. Because your own self-hosted Jentic One instance enforces the rules you set, you decide which of the four SSO Portal operations the agent may call. Since the bearer token and account id are passed as request parameters rather than resource ids in the path, you can scope the agent to read-only discovery with ListAccounts and ListAccountRoles while excluding GetRoleCredentials and Logout, or add credential exchange only for the accounts and roles it genuinely needs. Operations you do not grant stay unavailable to the agent.