openapi: 3.0.3 info: title: Flinks Outbound Auth API description: | Flinks Outbound Authentication API. Endpoints for generating authorization tokens and authenticating requests. version: 3.0.0 tags: - name: Authorization description: Endpoints for generating authorization tokens and authenticating requests servers: - url: https://{host} description: Flinks Outbound Auth Server variables: host: default: "{host}" description: Host URL paths: /api/v1/authorize: get: tags: - Outbound summary: Authorize With a Data Provider description: Use this endpoint to initiate the authorization process with a particular Data Provider. operationId: authorizeWithDataProvider parameters: - name: client_id in: query required: true description: The ID of the Data Recipient that you want to initiate the authorization process with. schema: type: string - name: redirect_uri in: query required: true description: The URI to redirect to after authorization is complete. schema: type: string - name: state in: query required: true description: A randomly generated, unique string that's linked to this particular request. This adds an extra layer of security and is an OAuth 2.0 standard. For the request to be successful, this string must be validated to confirm it's being passed with the correct request. schema: type: string - name: response_type in: query required: true description: Tells your server the type of response it can expect to receive from this request. For this use case, pass `code` as the value for this field to tell your server that you're sending an authorization code. schema: type: string default: code - name: scope in: query required: true description: | The scope of data that the Data Recipient collects from the customer, and is populated on the consent screen. To work with this Data Recipient, the customer must provide consent to share the scope of data they require. Possible values include: - `ACCOUNT_BASIC` - Basic account information - `ACCOUNT_DETAILED` - Detailed account information - `ACCOUNT_PAYMENTS` - Payment information linked to the account - `INVESTMENTS` - Investment information linked to the account - `STATEMENTS` - PDF statements for the account - `CUSTOMER_CONTACT` - Business contact information for the account - `CUSTOMER_PERSONAL` - Information about the customer who owns the account - `TRANSACTIONS` - List of transactions for the account This is a space separated list. The minimum scope required is `ACCOUNT_BASIC`. schema: type: string - name: provider_id in: query required: true description: The ID of the Data Provider that you are authorizing. schema: type: string - name: correlation_id in: query description: A randomly-generated, unique identifier that correlates two or more requests. schema: type: string - name: lang in: query description: | The language that you want to display on the consent screen: - `en` - English - `fr` - French If this field is left empty, the default value is English. schema: type: string default: en responses: "302": description: | Upon successful authorization, the user is redirected to the `redirect_uri` with a `code` parameter containing the authorization code and the `state` parameter. If authorization fails, the user is redirected to the `redirect_uri` with `error`, `error_description`, and `state` parameters. content: application/json: schema: type: object /api/v1/token: post: tags: - Outbound summary: Token description: Use the /api/v1/token endpoint to receive an access token. operationId: token requestBody: content: application/json: schema: type: object properties: grant_type: type: string description: | Specifies the type of information you are passing to request an access token. Possible values include: - `client_credentials` - `authorization_code` - `refresh_token` code: type: string description: The authorization code that you receive from the callback during the authorization process. Only pass this field if you are using `authorization_code` as the `grant_type`. redirect_uri: type: string description: The URL that you used in the authorization request. Must be an exact match. Only pass this field if you are using `authorization_code` as the `grant_type`. refresh_token: type: string description: The refresh token that you're exchanging for a new access token. Only pass this field if you are using `refresh_token` as the `grant_type`. scope: type: string description: Use for app management, only if you are using `client_credentials` as the `grant_type`. required: - grant_type example: {} responses: "200": description: | Returned when the token request is successful. The response varies based on the `grant_type`: - `refresh_token` - Returns `access_token`, `token_type`, and `expires_in`. - `authorization_code` - Returns `access_token`, `token_type`, `refresh_token`, and `expires_in`. - `client_credentials` - Returns `access_token`, `token_type`, and `expires_in`. content: application/json: schema: type: object properties: access_token: type: string description: The access token to use for authenticated requests. token_type: type: string description: The type of token. Value is `Bearer`. expires_in: type: integer default: 0 description: The number of seconds until the access token expires. refresh_token: type: string description: The refresh token to use to obtain a new access token. Only returned when using `authorization_code` as the grant type. scope: type: string description: The scope of data associated with the token. example: access_token: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx..." token_type: "Bearer" refresh_token: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" expires_in: 299 "4XX": description: Returned when the request is invalid or the grant type is not supported. content: application/json: schema: type: object properties: error: type: string description: The error code. error_description: type: string description: A description of the error. example: error: "unsupported_grant_type" error_description: "The authorization grant type is not supported by the authorization server." "5XX": description: Returned when an unhandled error occurred on the server. content: application/json: schema: type: object properties: error: type: string description: The error code. error_description: type: string description: A description of the error. example: error: "server_error" error_description: "An unhandled error occured on the server." /api/v1/providers: get: tags: - Outbound summary: List Active Data Providers (v1) description: Use the /api/v1/providers endpoint to list active Data Providers. operationId: listActiveDataProvidersV1 responses: "200": description: Returns an array of Data Provider objects. content: application/json: schema: type: array items: type: object properties: provider_id: type: integer description: The unique identifier of the Data Provider. name: type: string description: The name of the Data Provider. country: type: string description: The country the Data Provider operates in. example: - id: 1000 name: "FlinksCapital" "401": description: Returned when the access token is missing, invalid, or expired. content: application/json: schema: type: object properties: message: type: string example: message: "Unauthorized" "404": description: Returned when no Data Providers are found. content: application/json: schema: type: object /api/v2/providers: get: tags: - Outbound summary: List Active Data Providers (v2) description: Use the /api/v2/providers endpoint to list which Data Providers a particular Data Recipient is registered with. operationId: listActiveDataProvidersV2 parameters: - name: country in: query description: | Filter the results based on the country that the Data Provider operates in. Possible values include: - `CA` - Only include Data Providers operating in Canada - `US` - Only include Data Providers operating in the US - `CA,US` - Only include Data Providers operating in Canada and the US schema: type: string - name: isEnabledForClient in: query description: | Filter the results based on each Data Provider's current registration status with the Data Recipient (that is calling the endpoint). - `TRUE` - Returns only Data Providers with the status: `Activated` - `FALSE` - Returns only Data Providers with the statuses: `Available`, `PendingActivation`, `Suspended` If this parameter is excluded or blank, then all Data Providers in the system will be returned regardless of registration status. **Registration Statuses:** - `Activated` - Data Recipient has an active registration status with the Data Provider - `Available` - Data Recipient is not registered with the Data Provider - `PendingActivation` - A registration request with the Data Provider has been submitted, but not yet activated - `Suspended` - A previous registration with the Data Provider has been made inactive schema: type: boolean - name: connectorName in: query description: Filter the results based on the third-party provider that enables access to the Data Provider (such as 'akoya'). schema: type: string responses: "200": description: Result content: application/json: schema: type: array items: type: object properties: providerId: type: integer description: The unique identifier for the Data Provider. name: type: string description: The name of the Data Provider. country: type: string description: The country the Data Provider operates in (CA or US). scopes: type: array items: type: string description: The data scopes available from this Data Provider. status: type: string description: The registration status of this Data Provider for the Data Recipient. connectorName: type: string description: The third-party provider that enables access to this Data Provider. availableAccountTypes: type: object description: The types of accounts available from this Data Provider. properties: depositAccounts: type: string description: Availability of deposit accounts. investmentAccounts: type: string description: Availability of investment accounts. loanAccounts: type: string description: Availability of loan accounts. locAccounts: type: string description: Availability of line of credit accounts. example: - provider_id: 1234 name: "Example Bank" country: "CA" scopes: - "ACCOUNT_BASIC" - "ACCOUNT_DETAILED" - "TRANSACTIONS" status: "Activated" connectorName: "akoya" availableAccountTypes: depositAccounts: "true" investmentAccounts: "true" loanAccounts: "true" locAccounts: "false" "400": description: Client Error content: application/json: schema: type: object properties: title: type: string status: type: integer detail: type: string example: title: Bad Request status: 400 detail: The request parameters are invalid. "401": description: Unauthorized content: application/json: schema: type: object properties: title: type: string status: type: integer detail: type: string example: title: Unauthorized status: 401 detail: The access token is invalid or expired. "500": description: Returned when an internal server error occurred. content: application/json: schema: type: object properties: message: type: string description: Error message describing the server error. example: message: "Internal Server Error"