--- title: "Generate a widget access token" method: POST path: "/api/token/" tags: ["Widget Access Token"] --- # Generate a widget access token `POST /api/token/` Generate a widget access token for our Hosted Widget. ## Request body - union - WidgetTokenRequestBankingBrazil - `id` string, required — Your Belvo secretId. - `password` string, required — Your Belvo secretPassword. - `scopes` string, required — The scopes parameter contains a list of permissions that allow your to create a link for the user. This is a required parameter and must be sent exactly as shown. - `fetch_resources` string[], required — An array of resources that you would like to receive a historical update for. {% admonition type="warning" name="Wait for Webhooks Before Retrieving Data" %} After requesting resources using `fetch_resources`, you **must** wait for the historical update webhook from Belvo before retrieving the data. Making requests before receiving the webhook (GET or POST) will return empty or incomplete results. {% /admonition %} For OFDA Brazil, you can select the following resources: - `ACCOUNTS` - `OWNERS` - `TRANSACTIONS` - `BILLS` Additionally, you can opt-in to the following Open Finance specific resources (contact your representative as additional costs apply): - `INVESTMENTS` - `INVESTMENT_TRANSACTIONS` - `EXCHANGES` For OFDA, you can enable Enrichment resources for extended insights (contact your representative as additional costs apply): - `INCOMES` - `RECURRING_EXPENSES` - `RISK_INSIGHTS` {% admonition type="info" name="Enrichment Resources Require Transaction Data" %} To calculate enrichment resources (`INCOMES`, `RECURRING_EXPENSES`, `RISK_INSIGHTS`), you must also include `ACCOUNTS` and `TRANSACTIONS` in your `fetch_resources` array. Without these foundational resources, enrichment calculations will be incomplete or may not be generated. {% /admonition %} - `stale_in` string, required — Indicates how long any user-derived data should be stored in Belvo's database for the link (both single and recurrent). For example, if you send through `90d`, Belvo will remove any data from its database relating to the user after 90 days. For more information, check out the stale_in section of our Data retention controls article. > 📘 Info > > Belvo will only remove data for links that have not been updated in the period you provide in `stale_in`. Belvo will only remove data for links that have not been updated in the period you provide in `stale_in`. By default Belvo stores user data for 365 days, unless the link is deleted. - `widget` object, required — The `widget` object contains additional information about how to set up the widget, including custom branding, your terms and conditions, callback URLs, and information about the user you want to extract data for. - `openfinance_feature` string, required — The `openfinance_feature` parameter indicates that the end user will go through the OFDA flow. It must be set to `consent_link_creation` - `callback_urls` object, required — In the `callback_urls` object, you **must** add links to where your user should be redirected to in the following cases: - success (your user successfully connected their accounts) - exit (your user exited the widget before they completed the process) - event (an error occurred during the connection process) For more information, check out the callback_urls section in our Hosted Widget (OFDA) guide. > 📘 Callback Events > > Belvo will also send additional event information depending on the event. For more information, please make sure to check out the Handling callback events section of the Hosted Widget (OFDA) guide. - `success` string, required — The URL your user is redirected to when they successfully connects their account. - `exit` string, required — The URL your user is redirected to when they exit the process before connecting their account. - `event` string, required — The URL your user is redirected to when they encounter an error while connecting their account. - `branding` object, required — In the `branding` object, you **must** add your: - company_icon - company_logo - company_name - company_terms_url You can also optionally add a custom background color for when the widget opens, as well as disable Belvo's messaging regarding how many accounts have been connected. For more information about the branding and customization options of the widget, check out our dedicated guide. - `company_icon` string, uri, required — You can add your company icon to the widget to make it more aligned with your brand. For more information, see the company_icon section of our Branding and customization (OFDA) guide. - `company_logo` string, uri, required — You can add your company logo to the widget to make it more aligned with your brand. For more information, see the company_icon section of our Branding and customization (OFDA) guide. - `company_name` string, required — You can add your company name to be displayed when the widget first starts. By default, it'll just display "Link your account". When you add your company name, the message will follow the format "[company_name] uses Belvo to connect your account". For more information, see the company_name section of our Branding and customization (OFDA) guide. - `company_terms_url` string, uri, required — You can add a link to your privacy policy (or terms and conditions) on the initial screen of the widget that, when clicked, will redirect your users to the linked webpage. This helps your users better understand what your use case is regarding the data you are requesting. For more information, see the company_terms_url section of our Branding and customization (OFDA) guide. - `overlay_background_color` string — You can add a custom overlay color for when the widget loads in your desktop application. For more information, see the overlay_background_color section of our Branding and customization (OFDA) guide. - `social_proof` boolean — You can choose to hide the "Mais de 5 milhões de usuários já conectaram com segurança suas contas." message that appears when your user selects their institution in the widget. For more information, see the social_proof section of our Branding and customization (OFDA) guide. - `show_belvo_middle_logo` boolean — You can choose to display the Belvo logo between your company logo and the institution logo on the initial connect screen. When set to `true`, the Belvo logo will be displayed. Defaults to `false`. For more information, see the show_belvo_middle_logo section of our OFDA Widget Branding and Customization guide. - `theme` object[] — You can optionally add your brand colors to the widget using the `theme` parameter. For more information regarding where these colors will appear in the widget, check out the dedicated Add custom colors to the widget section of our Branding guide. - `css_key` string, required — CSS variable name. Possible values include: - `--color-primary-base` - `--nav-bar-title-color` - `--nav-bar-icon-color` - `value` string, required — The HEX code for the `css_key`. - `consent` object, required — The `consent` object is unique to the OFDA widget and must be sent through. - `purpose` string, required — In the `purpose` parameter, you can customize the messaging that is displayed to your user regarding for what use case you are requesting their data For more information, check out the purpose section in our Hosted Widget (OFDA) guide. - `terms_and_conditions_url` string, uri, required — In the `terms_and_conditions_url` parameter, you **must** provide a link to your company's terms and conditions. - `permissions` string[], required — The `permissions` parameter contains the resources that you want to extract from Brazil's Open Finance Network for the user. This value **must** be set to `["REGISTER", "ACCOUNTS", "CREDIT_CARDS","CREDIT_OPERATIONS"]`. - `identification_info` object[], required — In the `identification_info` array, you need to provide the identification information of the user that you want to retrieve information for. The information that you provide here must match the information that the regulated institution has for the user (for example, for businesses, the CPF and name must be for a user with access to the business account). - For individuals, you just need to provide the CPF and name. - For businesses, you need to provide both the CPF and CNPJ information. For more information, check out the identification_info section of our Hosted Widget (OFDA) guide. - `type` string, required — The identifier type. Can be either `CPF` or `CNPJ`. - `number` string, required — The CPF or CNPJ number of the individual or company associated with the identification. - `name` string, required — Name of the individual or company associated with the identification. - `default_consent_duration_days` 92 | 183 | 275 | 366 — You can preselect the consent duration in the dropdown menu. The `default_consent_duration_days` parameter accepts `366`, `275`, `183`, or `92` days (corresponding to 12, 9, 6, or 3 months). If you provide any other value, the dropdown will default to "Indeterminado" (indefinite). For more information, see the default_consent_duration_days section of our OFDA Widget Branding and Customization guide. - WidgetTokenRequestEmploymentBrazil - `id` string, required — Your Belvo secretId. - `password` string, required — Your Belvo secretPassword. - `scopes` string, required — The scopes parameter contains a list of permissions that allow your to create a link for the user. This is a required parameter and must be sent exactly as shown. - `fetch_resources` string[], required — An array of resources that you would like to receive a historical update for. For **Employments Brazil** (INSS), you can select the following resources: - `EMPLOYMENTS` - `OWNERS` - `stale_in` string, required — Indicates how long any user-derived data should be stored in Belvo's database for the link (both single and recurrent). For example, if you send through `90d`, Belvo will remove any data from its database relating to the user after 90 days. For more information, check out the stale_in section of our Data retention controls article. > 📘 Info > > Belvo will only remove data for links that have not been updated in the period you provide in `stale_in`. Belvo will only remove data for links that have not been updated in the period you provide in `stale_in`. By default Belvo stores user data for 365 days, unless the link is deleted. - `credentials_storage` string — Indicates whether or not to store credentials (and the duration for which to store the credentials). - For recurrent links, this is set to `store` by default (and cannot be changed). - For single links, this is set to `365d` by default. Can be either: - `store` to store credentials (until the link is deleted) - `nostore` to not store credentials - Any value between `1d` and `365d` to indicate the number of days you want the credentials to be stored. For more information, check out the credentials_storage section of our Data retention controls article. - `widget` object, required — The `widget` object contains additional information about how to set up the widget, including custom branding, your terms and conditions, callback URLs, and information about the user you want to extract data for. - `callback_urls` object — > 📘 Only required for the Hosted Widget. In the `callback_urls` object, you **must** add links to where your user should be redirected to in the following cases: - success (your user successfully connected their accounts) - exit (your user exited the widget before they completed the process) - event (an error occurred during the connection process) For more information, check out the callback_urls section in our Hosted Widget (Multi-Region) guide. > 📘 Callback Events > > Belvo will also send additional event information depending on the event. For more information, please make sure to check out the Handling callback events section of the Hosted Widget (Multi-Region) guide. - `success` string, required — The URL your user is redirected to when they successfully connects their account. - `exit` string, required — The URL your user is redirected to when they exit the process before connecting their account. - `event` string, required — The URL your user is redirected to when they encounter an error while connecting their account. - `branding` object, required — In the `branding` object, you **must** add your: - company_icon - company_logo - company_name - company_terms_url You can also optionally add a custom background color for when the widget opens, as well as disable Belvo's messaging regarding how many accounts have been connected. For more information about the branding and customization options of the widget, check out our dedicated guide. - `company_icon` string, uri, required — You can add your company icon to the widget to make it more aligned with your brand. For more information, see the company_icon section of our Branding and customization (Multi-Region) guide. - `company_logo` string, uri, required — You can add your company logo to the widget to make it more aligned with your brand. For more information, see the company_icon section of our Branding and customization (Multi-Region) guide. - `company_name` string, required — You can add your company name to be displayed when the widget first starts. By default, it'll just display "Link your account". When you add your company name, the message will follow the format "[company_name] uses Belvo to connect your account". For more information, see the company_name section of our Branding and customization (Multi-Region) guide. - `company_terms_url` string, uri, required — You can add a link to your privacy policy (or terms and conditions) on the initial screen of the widget that, when clicked, will redirect your users to the linked webpage. This helps your users better understand what your use case is regarding the data you are requesting. For more information, see the company_terms_url section of our Branding and customization (Multi-Region) guide. - `company_terms_version` string — The version of your terms and conditions. Use this parameter alongside `company_terms_url` to track which version of your T&C the user accepted during the widget flow. - `overlay_background_color` string — You can add a custom overlay color for when the widget loads in your desktop application. For more information, see the overlay_background_color section of our Branding and customization (Multi-Region) guide. - `social_proof` boolean — You can choose to hide the "Mais de 5 milhões de usuários já conectaram com segurança suas contas." message that appears when your user selects their institution in the widget. For more information, see the social_proof section of our Branding and customization (Multi-Region) guide. - `theme` object[] — You can optionally add your brand colors to the widget using the `theme` parameter. For more information regarding where these colors will appear in the widget, check out the dedicated Add custom colors to the widget section of our Branding guide. - `css_key` string, required — CSS variable name. Possible values include: - `--color-primary-base` - `--nav-bar-title-color` - `--nav-bar-icon-color` - `value` string, required — The HEX code for the `css_key`. - WidgetTokenRequestEmploymentMexico - `id` string, required — Your Belvo secretId. - `password` string, required — Your Belvo secretPassword. - `scopes` string, required — The scopes parameter contains a list of permissions that allow your to create a link for the user. This is a required parameter and must be sent exactly as shown. - `fetch_resources` string[], required — An array of resources that you would like to receive a historical update for. For **Employment Records Mexico** (IMSS and ISSSTE), you can select the following resources: - `EMPLOYMENT_RECORDS` Additionally, you can opt-in to the following Employment Record specific resources (contact your representative as additional costs apply): - `CURRENT_EMPLOYMENTS` (IMSS only) - `EMPLOYMENT_METRICS` (IMSS only) - `stale_in` string, required — Indicates how long any user-derived data should be stored in Belvo's database for the link (both single and recurrent). For example, if you send through `90d`, Belvo will remove any data from its database relating to the user after 90 days. For more information, check out the stale_in section of our Data retention controls article. > 📘 Info > > Belvo will only remove data for links that have not been updated in the period you provide in `stale_in`. Belvo will only remove data for links that have not been updated in the period you provide in `stale_in`. By default Belvo stores user data for 365 days, unless the link is deleted. - `credentials_storage` string — Indicates whether or not to store credentials (and the duration for which to store the credentials). - For recurrent links, this is set to `store` by default (and cannot be changed). - For single links, this is set to `365d` by default. Can be either: - `store` to store credentials (until the link is deleted) - `nostore` to not store credentials - Any value between `1d` and `365d` to indicate the number of days you want the credentials to be stored. For more information, check out the credentials_storage section of our Data retention controls article. - `widget` object, required — The `widget` object contains additional information about how to set up the widget, including custom branding, your terms and conditions, callback URLs, and information about the user you want to extract data for. - `callback_urls` object — > 📘 Only required for the Hosted Widget. In the `callback_urls` object, you **must** add links to where your user should be redirected to in the following cases: - success (your user successfully connected their accounts) - exit (your user exited the widget before they completed the process) - event (an error occurred during the connection process) For more information, check out the callback_urls section in our Hosted Widget (Multi-Region) guide. > 📘 Callback Events > > Belvo will also send additional event information depending on the event. For more information, please make sure to check out the Handling callback events section of the Hosted Widget (Multi-Region) guide. - `success` string, required — The URL your user is redirected to when they successfully connects their account. - `exit` string, required — The URL your user is redirected to when they exit the process before connecting their account. - `event` string, required — The URL your user is redirected to when they encounter an error while connecting their account. - `branding` object, required — In the `branding` object, you **must** add your: - company_icon - company_logo - company_name - company_terms_url You can also optionally add a custom background color for when the widget opens, as well as disable Belvo's messaging regarding how many accounts have been connected. For more information about the branding and customization options of the widget, check out our dedicated guide. - `company_icon` string, uri, required — You can add your company icon to the widget to make it more aligned with your brand. For more information, see the company_icon section of our Branding and customization (Multi-Region) guide. - `company_logo` string, uri, required — You can add your company logo to the widget to make it more aligned with your brand. For more information, see the company_icon section of our Branding and customization (Multi-Region) guide. - `company_name` string, required — You can add your company name to be displayed when the widget first starts. By default, it'll just display "Link your account". When you add your company name, the message will follow the format "[company_name] uses Belvo to connect your account". For more information, see the company_name section of our Branding and customization (Multi-Region) guide. - `company_terms_url` string, uri, required — You can add a link to your privacy policy (or terms and conditions) on the initial screen of the widget that, when clicked, will redirect your users to the linked webpage. This helps your users better understand what your use case is regarding the data you are requesting. For more information, see the company_terms_url section of our Branding and customization (Multi-Region) guide. - `company_terms_version` string — The version of your terms and conditions. Use this parameter alongside `company_terms_url` to track which version of your T&C the user accepted during the widget flow. - `overlay_background_color` string — You can add a custom overlay color for when the widget loads in your desktop application. For more information, see the overlay_background_color section of our Branding and customization (Multi-Region) guide. - `social_proof` boolean — You can choose to hide the "Mais de 5 milhões de usuários já conectaram com segurança suas contas." message that appears when your user selects their institution in the widget. For more information, see the social_proof section of our Branding and customization (Multi-Region) guide. - `theme` object[] — You can optionally add your brand colors to the widget using the `theme` parameter. For more information regarding where these colors will appear in the widget, check out the dedicated Add custom colors to the widget section of our Branding guide. - `css_key` string, required — CSS variable name. Possible values include: - `--color-primary-base` - `--nav-bar-title-color` - `--nav-bar-icon-color` - `value` string, required — The HEX code for the `css_key`. - WidgetTokenRequestFiscalMexico - `id` string, required — Your Belvo secretId. - `password` string, required — Your Belvo secretPassword. - `scopes` string, required — The scopes parameter contains a list of permissions that allow your to create a link for the user. This is a required parameter and must be sent exactly as shown. - `fetch_resources` string[], required — An array of resources that you would like to receive a historical update for. For **Fiscal Mexico** (SAT), you can select the following resources: - `FINANCIAL_STATEMENTS` - `INVOICES` - `TAX_COMPLIANCE_STATUS` - `TAX_RETENTIONS` - `TAX_RETURNS` - `TAX_STATUS` - `stale_in` string, required — Indicates how long any user-derived data should be stored in Belvo's database for the link (both single and recurrent). For example, if you send through `90d`, Belvo will remove any data from its database relating to the user after 90 days. For more information, check out the stale_in section of our Data retention controls article. > 📘 Info > > Belvo will only remove data for links that have not been updated in the period you provide in `stale_in`. Belvo will only remove data for links that have not been updated in the period you provide in `stale_in`. By default Belvo stores user data for 365 days, unless the link is deleted. - `credentials_storage` string — Indicates whether or not to store credentials (and the duration for which to store the credentials). - For recurrent links, this is set to `store` by default (and cannot be changed). - For single links, this is set to `365d` by default. Can be either: - `store` to store credentials (until the link is deleted) - `nostore` to not store credentials - Any value between `1d` and `365d` to indicate the number of days you want the credentials to be stored. For more information, check out the credentials_storage section of our Data retention controls article. - `widget` object, required — The `widget` object contains additional information about how to set up the widget, including custom branding, your terms and conditions, callback URLs, and information about the user you want to extract data for. - `callback_urls` object — > 📘 Only required for the Hosted Widget. In the `callback_urls` object, you **must** add links to where your user should be redirected to in the following cases: - success (your user successfully connected their accounts) - exit (your user exited the widget before they completed the process) - event (an error occurred during the connection process) For more information, check out the callback_urls section in our Hosted Widget (Multi-Region) guide. > 📘 Callback Events > > Belvo will also send additional event information depending on the event. For more information, please make sure to check out the Handling callback events section of the Hosted Widget (Multi-Region) guide. - `success` string, required — The URL your user is redirected to when they successfully connects their account. - `exit` string, required — The URL your user is redirected to when they exit the process before connecting their account. - `event` string, required — The URL your user is redirected to when they encounter an error while connecting their account. - `branding` object, required — In the `branding` object, you **must** add your: - company_icon - company_logo - company_name - company_terms_url You can also optionally add a custom background color for when the widget opens, as well as disable Belvo's messaging regarding how many accounts have been connected. For more information about the branding and customization options of the widget, check out our dedicated guide. - `company_icon` string, uri, required — You can add your company icon to the widget to make it more aligned with your brand. For more information, see the company_icon section of our Branding and customization (Multi-Region) guide. - `company_logo` string, uri, required — You can add your company logo to the widget to make it more aligned with your brand. For more information, see the company_icon section of our Branding and customization (Multi-Region) guide. - `company_name` string, required — You can add your company name to be displayed when the widget first starts. By default, it'll just display "Link your account". When you add your company name, the message will follow the format "[company_name] uses Belvo to connect your account". For more information, see the company_name section of our Branding and customization (Multi-Region) guide. - `company_terms_url` string, uri, required — You can add a link to your privacy policy (or terms and conditions) on the initial screen of the widget that, when clicked, will redirect your users to the linked webpage. This helps your users better understand what your use case is regarding the data you are requesting. For more information, see the company_terms_url section of our Branding and customization (Multi-Region) guide. - `company_terms_version` string — The version of your terms and conditions. Use this parameter alongside `company_terms_url` to track which version of your T&C the user accepted during the widget flow. - `overlay_background_color` string — You can add a custom overlay color for when the widget loads in your desktop application. For more information, see the overlay_background_color section of our Branding and customization (Multi-Region) guide. - `social_proof` boolean — You can choose to hide the "Mais de 5 milhões de usuários já conectaram com segurança suas contas." message that appears when your user selects their institution in the widget. For more information, see the social_proof section of our Branding and customization (Multi-Region) guide. - `theme` object[] — You can optionally add your brand colors to the widget using the `theme` parameter. For more information regarding where these colors will appear in the widget, check out the dedicated Add custom colors to the widget section of our Branding guide. - `css_key` string, required — CSS variable name. Possible values include: - `--color-primary-base` - `--nav-bar-title-color` - `--nav-bar-icon-color` - `value` string, required — The HEX code for the `css_key`. ## Response `200` Successful operation - WidgetToken - `access` string — The access token to be used to authenticate the widget. - `refresh` string — The refresh token to be used to authenticate the widget. ## Other responses - `400` — Bad request error - `500` — Unexpected Error --- [API](https://skmtc.net/belvo/apis/belvo-api-docs.md) · [All operations](https://skmtc.net/belvo/apis/belvo-api-docs/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/belvo/belvo-api-docs/revisions/3423c786ece5/schema)