> For the complete documentation index, see [llms.txt](https://docs.sudoplatform.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sudoplatform.com/guides/entitlements/end-user-api/redeeming-entitlements.md). # Redeeming Entitlements A federated user must be registered with the Sudo Platform entitlements service before they can access other entitled services in their environment. This process is called *redeeming entitlements.* Entitlement redemption must occur the first time a federated user signs in to the Sudo Platform. However, it is an idempotent operation and subsequent calls will have no effect. The redemption operation uses information in the user's identity token and takes no parameters. {% tabs %} {% tab title="Swift" %} ```swift do { let redeemed = try await entitlementsClient.redeemEntitlements() // Handle success } catch { // Handle error } ``` {% endtab %} {% tab title="Kotlin" %} ```kotlin try { val entitlements = entitlementsClient.redeemEntitlements() // Handle redeemed entitlements } catch (e: SudoEntitlements.EntitlementsException) { // Handle error } ``` {% endtab %} {% tab title="JavaScript" %} ```javascript try { const entitlements = await entitlementsClient.redeemEntitlements() // Handle redeemed entitlements } catch (err) { // Handle error } ``` {% endtab %} {% endtabs %} The `redeemEntitlements` method returns the user's entitlements. See the [API Reference](/guides/entitlements/end-user-api/api-reference.md) for details of the returned structure. ## Errors The `redeemEntitlements` API will throw errors in the the following circumstances: {% tabs %} {% tab title="Swift" %} | | | | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | **Condition** | Action | | | `.notSignedIn` | User was not signed in when `redeemEntitlements` was invoked. | Ensure user is signed in prior to invoking `redeemEntitlements` | | `.ambiguousEntitlements` | User has been configured to match more than one entitlements set. | Ensure your identity provider has been set up to include claims that in the user's token that will map to exactly one entitlements set. | | `.invalidToken` | The user's token does not contain a claim that can be mapped to an entitlements set, or has the user been pre-configured with initial entitlements. | Ensure your identity provider has been set up to include an expected claim when federating sign-on or pre-configure the user with entitlements. | | `.serviceError` | A transient error occurred in the service while redeeming entitlements. | Retry the request. If the problem persists, [ask us for help](https://sudoplatform.com/#lets-chat) | | {% endtab %} | | | {% tab title="Kotlin" %} Errors in Kotlin are thrown as exceptions in the `SudoEntitlementsClient.EntitlementsException` class name space. | | | | | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | **Condition** | Action | | | `NotSignedInException` | User was not signed in when `redeemEntitlements` was invoked. | Ensure user is signed in prior to invoking `redeemEntitlements` | | `AmbiguousEmtitlementsException` | User has been configured to match more than one entitlements set. | Ensure your identity provider has been set up to include claims that in the user's token that will map to exactly one entitlements set. | | `InvalidTokenException` | The user's token does not contain a claim that can be mapped to an entitlements set, or has the user been pre-configured with initial entitlements. | Ensure your identity provider has been set up to include an expected claim when federating sign-on or pre-configure the user with entitlements. | | `UnknownException` | A transient error occurred in the service while redeeming entitlements. | Retry the request. If the problem persists, [ask us for help](https://sudoplatform.com/#lets-chat) | | {% endtab %} | | | {% tab title="JavaScript" %} | | | | | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | **Condition** | Action | | | `NotSignedInError` | User was not signed in when `redeemEntitlements` was invoked. | Ensure user is signed in prior to invoking `redeemEntitlements` | | `AmbiguousEntitlementsError` | User has been configured to match more than one entitlements set. | Ensure your identity provider has been set up to include claims that in the user's token that will map to exactly one entitlements set. | | `InvalidTokenError` | The user's token does not contain a claim that can be mapped to an entitlements set, or has the user been pre-configured with initial entitlements. | Ensure your identity provider has been set up to include an expected claim when federating sign-on or pre-configure the user with entitlements. | | `ServiceError` | A transient error occurred in the service while redeeming entitlements. | Retry the request. If the problem persists, [ask us for help](https://sudoplatform.com/#lets-chat) | | {% endtab %} | | | | {% endtabs %} | | | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.sudoplatform.com/guides/entitlements/end-user-api/redeeming-entitlements.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.