openapi: 3.1.0 info: version: '3.3.0' # build: '0' title: Truist Retail OAuth 2.0 API, v3 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: ############################################################ # # 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: 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. parameters: ############################################################ # # Request parameters # ############################################################ 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 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 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' 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 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 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. | Value | Description | |-----|-----| | BROKERAGEPRODUCT | Investment management offered by a licensed brokerage firm that places trades on behalf of the customer, utilizing any number of investment options | | 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 | | CHECKING | A deposit account held at a financial institution that allows withdrawals and deposits | | COMMERCIALLOAN | A preset borrowing limit that can be used at any time | | CREDITCARD | Allows cardholders to borrow funds with which to pay for goods and services with merchants that accept cards for payment | | IRA | An individual retirement account (IRA) is a tax-advantaged account that individuals use to save and invest for retirement | | 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 | | MORTGAGE | A type of loan you can use to buy or refinance a home | | PERSONALLOAN | A type of debt that is not protected by a guarantor, or collateralized by a lien on specific assets of the borrower | | SAVINGS | An interest-bearing deposit account held at a bank or other financial institution | | 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 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 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 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 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 headers: ############################################################ # # Standard response headers # ############################################################ x-fapi-interaction-id: description: Unique request identifier required: true schema: type: string example: rrt-970585410023330903-b-gce-821-23397-1 schemas: ############################################################ # # Data entities # ############################################################ 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 APIErrorResponse: type: object required: - error properties: error: type: string description: Enumerated value of error type error_description: type: string description: Description of the error Error: type: object properties: code: type: string description: >- Error code defined by FDX API Specification or Data Provider indicating the error situation which has occurred message: type: string description: >- End user displayable information which might help the customer diagnose an error required: - code - message 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 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 Scope: title: Scope description: The enum values of defined scopes. Scope offline_access must be included to get back refresh_tokens type: string enum: - openid - profile - email - address - phone - offline_access - ACCOUNT_DETAILED - ACCOUNT_BASIC - CUSTOMER_CONTACT - PAYMENT_SUPPORT - TRANSACTIONS 302RedirectURI: type: string description: Success Response example: 'https://example-app.com/callback?code=fogeqqbz2xi23hvgvlu4ka2kq&state=123abc' 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' 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' 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' 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' 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' 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' 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' 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' 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' 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' 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' 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' 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' 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' 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'