openapi: 3.2.0 info: version: 3.3.0 title: Truist Retail API, v3 OAuth 2.0 API description: Truist Financial, Access Management - OAuth 2.0 API, v3 contact: name: Truist API Support url: https://developer.truist.com/contact-us servers: - url: https://api-sandbox.truist.com/retail/auth/oauth description: Truist Financial Retail Authorization API - Sandbox environment - url: https://apicert.truist.com/retail/auth/oauth description: Truist Financial Retail Authorization API - Certification environment - url: https://api.truist.com/retail/auth/oauth description: Truist Financial Retail Authorization API - Production environment security: - BasicAuth: [] - OAuth: - profile - address - phone - email tags: - name: OAuth 2.0 description: OAuth 2.0 authorize and token services paths: /v3/authorize: get: operationId: authorize servers: - url: https://api-sandbox.truist.com/retail/auth/oauth description: Truist Financial Retail authorization tags: - OAuth 2.0 summary: Get authorization from the resource owner description: 'The `/authorize` endpoint is used to interact with the resource owner and obtain an authorization code. Because this endpoint uses browser-based redirection to pass back the resulting authorization code, it cannot be tested in the Truist Developer Center through the Swagger UI plugin''s "Try It Out" feature or "Send API Request" button. The simplest way to test this API in Truist Sandbox environment will be to update and use following `cURL` sample: 1. Enter your Sandbox app''s `client_id` (even for DAPs, since a DAP cannot create real DR IDs in Sandbox) 2. Enter your valid `redirect_uri`. A good option to use is `https://localhost` 3. Use the default `scope` value or update to add others like TRANSACTIONS 4. Use the default or any other value for the `state` parameter 5. Select the `Shell / cURL` option for the **Request Sample** box 6. Copy the contents of the cURL example and execute on the command line The cURL command will look something like this: ```bash curl --request GET \ --url ''https://apidev-sandbox.truist.com/retail/auth/oauth/v3/authorize?client_id=asdfsadfsdf&response_type=code&redirect_uri=https%3A%2F%2Flocalhost&cardinality=SINGLE&accountType=CHECKING+CREDITCARD+SAVINGS+TRUST&scope=openid+offline_access+ACCOUNT_BASIC+ACCOUNT_DETAILED&state=unique_request_state_code'' ```' parameters: - $ref: '#/components/parameters/client_id' - $ref: '#/components/parameters/response_type' - $ref: '#/components/parameters/redirect_uri' - $ref: '#/components/parameters/cardinality' - $ref: '#/components/parameters/accountType' - $ref: '#/components/parameters/scope' - $ref: '#/components/parameters/state' - $ref: '#/components/parameters/nonce' responses: '302': description: Redirect URI response headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' Location: schema: anyOf: - $ref: '#/components/schemas/302RedirectURI' - $ref: '#/components/schemas/302MissingScope' - $ref: '#/components/schemas/302MissingResponseType' - $ref: '#/components/schemas/302UnsupportedResponseType' - $ref: '#/components/schemas/302InvalidScope' - $ref: '#/components/schemas/302MissingValidScope' - $ref: '#/components/schemas/302MissingState' - $ref: '#/components/schemas/302MissingNonce' - $ref: '#/components/schemas/302ServerError' - $ref: '#/components/schemas/302Unavailable' - $ref: '#/components/schemas/302RequestNotSupported' - $ref: '#/components/schemas/302RequestURINotSupported' - $ref: '#/components/schemas/302RegistrationNotSupported' - $ref: '#/components/schemas/302UserDenied' - $ref: '#/components/schemas/302InvalidCardinality' - $ref: '#/components/schemas/302AccountTypesNotSupported' '400': description: Bad Request headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' examples: missingClientId: summary: Missing Client ID value: error: invalid_request error_description: 'The request is missing required parameter: client_id' missingRedirectURI: summary: Missing Redirect URI value: error: invalid_request error_description: 'The request is missing required parameter: redirect_uri' invalidRedirectURI: summary: Invalid Redirect URI value: error: invalid_request error_description: The redirect_uri is invalid '401': description: Unauthorized headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' examples: unauthorized_client: summary: Unauthorized Client value: error: unauthorized_client error_description: The client is not authorized to request an authorization code using this method security: [] /v3/token: parameters: - $ref: '#/components/parameters/FapiInteractionIdHeader' - $ref: '#/components/parameters/FdxApiActorTypeHeader' post: operationId: token servers: - url: https://api-sandbox.truist.com/retail/auth/oauth description: Truist Financial Retail authorization tags: - OAuth 2.0 summary: Get an access token description: Use the `/token` endpoint to exchange a customer's new authorization_code or their existing consent's refresh_token for a new access_token. This API uses Basic Auth and for both Data Access Platforms and Direct Data Recipients requires use of the DAP/DDR client_id and client_secret returned from creating the Staging or Production application in Truist Developer Center. (You CANNOT use a Data Recipient's Basic Auth credentials of client_id and client_secret from dynamic client registration via `POST /register` API) requestBody: required: true content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/TokenRequest' responses: '200': description: The authorization server issues an access token and optional refresh token and/or id token headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' content: application/json: schema: $ref: '#/components/schemas/TokenResponse' example: grant_id: as9d8f3219dj access_token: SlAV32hkKG token_type: Bearer expires_in: 900 refresh_token: 8xLOxBtZp8 refresh_token_expires_in: 7775999 scope: ACCOUNT_BASIC TRANSACTIONS ACCOUNT_DETAILED address email openid phone profile offline_access id_token: eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.ewogImlzc yI6ICJodHRwOi8vc2VydmVyLmV4YW1wbGUuY29tIiwKICJzdWIiOiAiMjQ4Mjg5 NzYxMDAxIiwKICJhdWQiOiAiczZCaGRSa3F0MyIsCiAibm9uY2UiOiAibi0wUzZ fV3pBMk1qIiwKICJleHAiOiAxMzExMjgxOTcwLAogImlhdCI6IDEzMTEyODA5Nz AKfQ.ggW8hZ1EuVLuxNuuIJKX_V8a_OMXzR0EHR9R6jgdqrOOF4daGU96Sr_P6q Jp6IcmD3HP99Obi1PRs-cwh3LO-p146waJ8IhehcwL7F09JdijmBqkvPeB2T9CJ NqeGpe-gccMg4vfKjkM8FcGvnzZUN4_KSP0aAp1tOJ1zZwgjxqGByKHiOtX7Tpd QyHE5lcMiKPXfEIQILVq0pc_E2DzL7emopWoaoZTF_m0_N0YzFC6g6EJbOEoRoS K5hoDalrcvRYLSrQAZZKflyuVCyixEoV9GfNQC3_osjzw2PAithfubEEBLuVVk4 XUVrWOLrLl0nx7RkKU8NXNHq-rvKMzqg '400': description: Bad Request headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' examples: missingClientId: summary: Missing Client ID value: error: invalid_request error_description: 'The request is missing required parameter: client_id' missingRedirectURI: summary: Missing Redirect URI value: error: invalid_request error_description: 'The request is missing required parameter: redirect_uri' invalidRedirectURI: summary: Invalid Redirect URI value: error: invalid_request error_description: A redirect_uri is invalid invalidRefreshToken: summary: Invalid Refresh Token value: error: invalid_grant error_description: The refresh token is invalid revokedRefreshToken: summary: Revoked refresh token value: error: invalid_grant error_description: The refresh token is revoked. expiredRefreshToken: summary: Expired refresh token value: error: invalid_grant error_description: The refresh token is expired. revokedConsent: summary: Revoked consent value: error: invalid_grant error_description: This consent was revoked expiredConsent: summary: Expired consent value: error: invalid_grant error_description: This consent was expired invalidAuthCode: summary: Invalid AuthCode description: Missing or invalid auth code value: error: invalid_grant error_description: The auth code is invalid invalidGrantType: summary: Invalid Grant Type value: error: unsupported_grant_type error_description: The given grant_type is not supported '401': description: Invalid Client headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' examples: invalid_client: summary: Invalid Client value: error: invalid_client error_description: Client authentication failed '404': description: Not Found headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' examples: not_found: summary: Not Found value: error: not_found error_description: URI does not represent a recognized resource '405': description: The request method is not supported by this resource headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' examples: not_found: summary: Method Not Allowed value: error: invalid_method error_description: The request method is not supported by this resource security: - BasicAuth: [] components: schemas: 302RequestNotSupported: type: string description: The request parameter is not supported example: https://example-app.com/callback?error=request_not_supported&error_description=The%20request%20parameter%20is%20not%20supported&state=12345 TokenResponse: type: object properties: grant_id: type: string description: The consent id that can be used by data recipient to view the Consent grant access_token: type: string description: The access token issued by the authorization server token_type: type: string description: The type of the token issued (default Bearer) expires_in: type: integer description: The lifetime in seconds of the access token. The value "900" denotes that the access token will expire in 15 minutes from the time the response was generated. If omitted, the authorization server SHOULD provide the expiration time via other means or document the default value. refresh_token: type: string description: OPTIONAL. The refresh token, which can be used to obtain new access tokens using the same authorization grant refresh_token_expires_in: type: integer description: The lifetime in seconds of the refresh token. The value "7775999" denotes that the refresh token will expire in ninety days from the time the response was generated. If omitted, the authorization server SHOULD provide the expiration time via other means or document the default value. scope: type: string description: A space-delimited array of '#/components/schemas/Scope' enum values. Scope offline_access must be included to get back refresh_tokens id_token: type: string description: OPTIONAL, OpenID Connect ID Token 302MissingValidScope: type: string description: The requested scopes are not valid for data recipient example: https://example-app.com/callback?error=invalid_scope&error_description=The%20requested%20scopes%20are%20not%20valid%20for%20data%20recipient&state=12345 302MissingScope: type: string description: 'The request is missing a required parameter: scope' example: https://example-app.com/callback?error=invalid_request&error_description=The%20request%20is%20missing%20a%20required%20parameter%20%3A%scope&state=12345 APIErrorResponse: type: object required: - error properties: error: type: string description: Enumerated value of error type error_description: type: string description: Description of the error 302UnsupportedResponseType: type: string description: The authorization server does not support obtaining an authorization code using this method example: https://example-app.com/callback?error=unsupported_response_type&error_description=The%20authorization%20server%20does%20not%20support%20obtaining%20an%20authorization%20code%20using%20this%20method&state=12345 302MissingNonce: type: string description: 'The request is missing a required parameter: nonce' example: https://example-app.com/callback?error=invalid_request&error_description=The%20request%20is%20missing%20a%20required%20parameter%20%3A%nonce&state=1234 302RedirectURI: type: string description: Success Response example: https://example-app.com/callback?code=fogeqqbz2xi23hvgvlu4ka2kq&state=123abc 302MissingResponseType: type: string description: Missing response type example: https://example-app.com/callback?error=invalid_request&error_description=The%20request%20is%20missing%20a%20required%20parameter%20%3A%20response_type&state=12345 302MissingState: type: string description: 'The request is missing a required parameter: state' example: https://example-app.com/callback?error=invalid_request&error_description=The%20request%20is%20missing%20a%20required%20parameter%20%3A%state 302Unavailable: type: string description: The authorization server is currently unable to handle the request example: https://example-app.com/callback?error=temporarily_unavailable&error_description=The%20authorization%20server%20is%20currently%20unable%20to%20handle%20the%20request&state=12345 302RegistrationNotSupported: type: string description: The registration parameter is not supported example: https://example-app.com/callback?error=registration_not_supported&error_description=The%20registration%20parameter%20is%20not%20supported&state=12345 302RequestURINotSupported: type: string description: The request_uri parameter is not supported example: https://example-app.com/callback?error=request_uri_not_supported&error_description=The%20request_uri%20parameter%20is%20not%20supported&state=1234 302InvalidScope: type: string description: The requested scope is invalid, unknown, or malformed example: https://example-app.com/callback?error=invalid_scope&error_description=The%20requested%20scope%20is%20invalid%2C%20unknown%2C%20or%20malformed&state=12345 302ServerError: type: string description: The authorization server encountered an unexpected condition that prevented it from fulfilling the request example: https://example-app.com/callback?error=server_error&error_description=The%20authorization%20server%20encountered%20an%20unexpected%20condition%20that%20prevented%20it%20from%20fulfilling%20the%20request&state=12345 TokenRequest: type: object properties: client_id: description: REQUIRED, or OMIT if Authorization header is passed type: string client_secret: description: REQUIRED, or OMIT if Authorization header is passed type: string grant_type: description: Grant type used to specify request for auth code or refresh token type: string enum: - authorization_code - refresh_token code: description: REQUIRED for grant_type 'authorization_code', OMIT for 'refresh_token'. The authorization_code received from the authorization server (Authorization Code Flow) type: string redirect_uri: description: REQUIRED. MUST match the 'redirect_uri' parameter included in the authorization request (Authorization Code Flow) type: string format: uri refresh_token: description: REQUIRED for grant_type 'refresh_token', OMIT for 'authorization_code'. The refresh_token issued to the client (Refresh Token Flow) type: string required: - grant_type - code - redirect_uri 302UserDenied: type: string description: The user denied the request example: https://example-app.com/callback?error=user_denied&error_description=The%20user%20denied%20the%20request&state=12345 302AccountTypesNotSupported: type: string description: None of the requested accountTypes are supported example: https://example-app.com/callback?error=invalid_request&error_description=None%20of%20the%20requested%20accountTypes%20are%20supported ActorType: title: FDX API Actor Type description: Indicates whether a customer is present and has requested the operation (USER), or if a batch job has requested the operation (BATCH) type: string enum: - BATCH - USER 302InvalidCardinality: type: string description: The requested cardinality is unknown, use SINGLE or MULTIPLE example: https://example-app.com/callback?error=invalid_request&error_description=The%20requested%20cardinality%20is%20unknown%2C%20use%20SINGLE%20or%20MULTIPLE parameters: state: in: query name: state description: An opaque value used by the client to maintain state between the request and callback required: true schema: type: string example: unique_request_state_code scope: in: query name: scope description: The space-delimited string array of scopes requested. For OpenID Connect, scopes can be used to request that specific sets of information be made available as Claim Values. Scope 'offline_access' must be included to get back refresh_tokens required: true schema: description: 'A space-delimited string containing values from the enumerated list in $ref: ''#/components/schemas/Scope''' type: string example: openid offline_access ACCOUNT_BASIC ACCOUNT_DETAILED redirect_uri: in: query name: redirect_uri description: After completing its interaction with the resource owner, the authorization server directs the resource owner's user-agent back to the client required: true schema: type: string example: https://example-app.com/callback nonce: in: query name: nonce description: nonce is an optional String value used to associate a Client session with an ID Token, and to mitigate replay attacks. It MUST be present if authorization server issues an ID Token in the Token response (openid scope included in request). required: false schema: type: string response_type: in: query name: response_type description: The client informs the authorization server of the desired grant type flow using the response_type parameter required: true schema: type: string enum: - code example: code accountType: in: query name: accountType description: "A space-delimited string array of the only account types which Data Recipient can support in customer consents. This value is used by Truist consent creation and management UIs to filter the customer accounts presented for selection. If not specified the default is that customer account list will not be filtered on behalf of Data Recipient.\n | Value | Description |\n |-----|-----|\n | BROKERAGEPRODUCT | Investment management offered by a licensed brokerage firm that places trades on behalf of the customer, utilizing any number of investment options |\n | CD | A certificate of deposit (CD) is a product offered by banks and credit unions that provides an interest rate premium in exchange for the customer agreeing to leave a lump-sum deposit untouched for a predetermined period of time |\n | CHECKING | A deposit account held at a financial institution that allows withdrawals and deposits |\n | COMMERCIALLOAN | A preset borrowing limit that can be used at any time |\n | CREDITCARD | Allows cardholders to borrow funds with which to pay for goods and services with merchants that accept cards for payment |\n | IRA | An individual retirement account (IRA) is a tax-advantaged account that individuals use to save and invest for retirement |\n | LINEOFCREDIT | A credit facility extended by a bank or other financial institution to a government, business or individual customer that enables the customer to draw on the facility when the customer needs funds |\n | MORTGAGE | A type of loan you can use to buy or refinance a home |\n | PERSONALLOAN | A type of debt that is not protected by a guarantor, or collateralized by a lien on specific assets of the borrower |\n | SAVINGS | An interest-bearing deposit account held at a bank or other financial institution |\n | TRUST | A type of financial account that is opened by an individual and managed by a designated trustee for the benefit of a third party in accordance with agreed-upon terms |" required: false schema: type: string example: CHECKING CREDITCARD SAVINGS TRUST FapiInteractionIdHeader: name: x-fapi-interaction-id in: header description: Unique request identifier required: true schema: type: string example: rrt-970585410023330903-b-gce-821-23397-1 FdxApiActorTypeHeader: name: FDX-API-Actor-Type in: header description: Identifies whether the customer is present (USER) or it is a BATCH operation schema: $ref: '#/components/schemas/ActorType' example: BATCH client_id: in: query name: client_id description: The client_id parameter for `/authorize` endpoint must represent the ultimate data recipient to which customer is consenting their data sharing. For a Data Access Platform (aggregator) that will be the DR ID returned from its dynamic client registration via `POST /register` API. For a Direct Data Recipient that will be the client_id returned from creating the Staging or Production application in Truist Developer Center required: true schema: type: string example: xbyFy0fCqucBKz5jwvXMUNvoBZL4QHir cardinality: in: query name: cardinality description: 'Specifies whether the Data Recipient can support only one or more than one account in customer consents. SINGLE: Data Recipient can only support exactly one account. MULTIPLE: Data Recipient can support any number of accounts. This is the default if neither is specified. This value is used by Truist consent creation and management UIs to display the corresponding account selection requirement to customers.' required: false schema: type: string enum: - SINGLE - MULTIPLE example: SINGLE headers: x-fapi-interaction-id: description: Unique request identifier required: true schema: type: string example: rrt-970585410023330903-b-gce-821-23397-1 securitySchemes: BasicAuth: type: http scheme: basic description: This is the standard Basic Auth scheme encoded as `Base64(client_id:client_secret)`. Both Data Access Platforms and Direct Data Recipients MUST use the DAP/DDR client_id and client_secret returned from creating their Staging or Production application in Truist Developer Center. (You CANNOT use the Basic Auth credentials for a Data Recipient returned from dynamic client registration via `POST /register` API) OAuth: type: oauth2 description: The production authorization URL will be provided after the onboarding process is completed. flows: authorizationCode: authorizationUrl: https://api-sandbox.truist.com/retail/auth/oauth/v3/authorize tokenUrl: https://api-sandbox.truist.com/retail/auth/oauth/v3/token scopes: profile: This scope value requests access to the End-User's default profile Claims, which are:name, family_name, given_name, middle_name, zoneinfo, locale, and updated_at. address: This scope value requests access to the email and email_verified Claims. phone: This scope value requests access to the address Claim email: This scope value requests access to the phone_number and phone_number_verified Claims.