Connect API v2 (BETA)

This API handles the lifecycle of Connections inside Flanks.

Endpoints

Connectors

List Connectors

Return all the connectors available, matching the given query.

This is a paginated endpoint. If the response returns a next_page_token, you can use it to fetch the next page using the page_token parameter in the next request. If the request does not return a next_page_token, then there are no more pages to fetch.

https://api.flanks.io/connect/v2/connectors/list-connectors

Headers

Header	Value
`Authorization`	`Bearer <access_token>` (See Authentication).
`Content-Type`	`application/json`

Body (JSON encoded)

Parameter	Type	Description
`query` *	object	The Query object
`page_token`	string	If provided, the request will fetch the next page for this query

(*) Mandatory Parameters

Query Object

We will return all the items that match all the fields in the query.

For each Field, if the Type is an Array, we'll return items that match any of the values in the array. If the field contains an empty array, we will return no items.

If the query is empty, we'll return all the items.

Field	Type	Description
`connector_id_in`	[string]	The unique identifier of the connector

Responses

200 OK

  {
    "items": [{ Connector }],
    "next_page_token": string | null,
  }

Returns a paginated result, where items will be a list of Connectors.

400 Validation Error

{
    "success": false,
    "error": {
        "code": "ValidationError",
        "details": [
            { "error_type": string, "field": string },
            ...
        ],
    },
    "trace_id": string,
}

Some fields are missing or incorrect.

401 Invalid Credentials

{
    "error": "Invalid credentials"
}

The Authorization header is either empty or contains an invalid or expired access_token.

500 Internal Error

{
    "error": "Internal Error"
}

The server encountered an unexpected condition that prevented it from fulfilling the request.

Sessions

Create Session

Create a new Session with the given configuration.

https://api.flanks.io/connect/v2/sessions/create-session

Headers

Header	Value
`Authorization`	`Bearer <access_token>` (See Authentication).
`Content-Type`	`application/json`

Body (JSON encoded)

Parameter	Type	Value
`configuration` *	object	See Session Configuration

(*) Mandatory Parameters

Responses

200 OK

    { session: Sesssion }

Returns the new session. See Connect Session Model.

400 Validation Error

{
    "success": false,
    "error": {
        "code": "ValidationError",
        "details": [
            { "error_type": string, "field": string },
            ...
        ],
    },
    "trace_id": string,
}

Some fields are missing or incorrect.

401 Invalid Credentials

{
    "error": "Invalid credentials"
}

The Authorization header is either empty or contains an invalid or expired access_token.

500 Internal Error

{
    "error": "Internal Error"
}

The server encountered an unexpected condition that prevented it from fulfilling the request.

List Sessions

Return all the sessions matching the given query.

This is a paginated endpoint. If the response returns a next_page_token, you can use it to fetch the next page using the page_token parameter in the next request. If the request does not return a next_page_token, then there are no more pages to fetch.

https://api.flanks.io/connect/v2/sessions/list-sessions

Headers

Header	Value
`Authorization`	`Bearer <access_token>` (See Authentication).
`Content-Type`	`application/json`

Body (JSON encoded)

Parameter	Type	Description
`query` *	object	The Query object
`page_token`	string	If provided, the request will fetch the next page for this query

(*) Mandatory Parameters

Query Object

We will return all the items that match all the fields in the query.

For each Field, if the Type is an Array, we'll return items that match any of the values in the array. If the field contains an empty array, we will return no items.

If the query is empty, we'll return all the items.

Field	Type	Description
`session_id_in`	[string]	Unique identifier for the session
`status_in`	[string]	The Status of the sesssion
`connection_id_in`	[string \| null]	Unique identifier for the connection associated to the Session. If set to `null`, means the session does not have a connection yet
`error_code_in`	[string \| null]	The Error Code of the Session. If set to `null`, means filtering for sessions with no error.

Responses

200 OK

  {
    "items": [{ Session }],
    "next_page_token": String | null,
  }

Returns a paginated result, where items will be a list of Sessions.

400 Validation Error

{
    "success": false,
    "error": {
        "code": "ValidationError",
        "details": [
            { "error_type": string, "field": string },
            ...
        ],
    },
    "trace_id": string,
}

Some fields are missing or incorrect.

401 Invalid Credentials

{
    "error": "Invalid credentials"
}

The Authorization header is either empty or contains an invalid or expired access_token.

500 Internal Error

{
    "error": "Internal Error"
}

The server encountered an unexpected condition that prevented it from fulfilling the request.

Data Model

Connector Model

{
  "name": string,
  "id": string,
}

Session Model

{
  "attributes": SessionnAttributes,
  "configuration": SessionConfiguration,
  "connection": SessionConnection | null,
  "error": SessionError | null,
}

All sessions have attributes and configuration. If the connection hasn't been stablished yet, the field will be null. This will be the default state for new sessions.

Session Attributes

{
    "created_at": string, // (ISO 8601, example: "2025-12-31T23:59:59.123456+00:00" )
    "id": string,
    "status": SessionStatus,
    "updated_at": string, // (ISO 8601, example: "2025-12-31T23:59:59.123456+00:00" )
    "url": string,
}

Session Status

It's a string that represents the current status of the session. Can have the following values:

Waiting:ProvideCredentials
Waiting:Challenge
Processing:ProvideCredentials
Processing:Challenge
Finished:OK
Finished:Error

Session Configuration

{
    "skip_psd2_notice": boolean, // Default: false
    "connection_id": string | null,
    "connector_id": string | null,
    "context": object, // Default: {}
    "expires_at": string, // (ISO 8601, example: "2025-12-31T23:59:59.123456+00:00" )
    "language": string, // Default: "en"
    "labels": object | null // Example: {"foo": "bar"}
    "redirect_url": string,
}

Available values for language are:

en (English)
es (Spanish)
fr (French)
sv (Swedish)

The field skip_psd2_notice defaults to false. If set to true, the widget will not display the user acceptance notice, instead it will directly redirect to the PSD2 login page.

The field expires_at defaults to 15 days from the creation date.

The field connector_id will be ignored if the field connection_id is set.

This field context is an arbitrary JSON object. This field is not used by our system, but provided as a benefit of the consumer: we'll store exactly what's provided on session creation and do nothing with it. You can use this to store information that you deem useful when the user is returned to your system with a session_id. For example, you can store the id of the event that triggered the session in your system to have a reference.

This field labels is a dictionary where both the keys and the values are strings. The labels value will be copied to the connection once it's created. They will be returned when listing sessions and connections, but they can also be used for filtering the results.

Session Connection

{
    "connector_id": string,
    "id": string,
}

Session Error

{
    "code": string,
}

Code can have the following values:

InvalidCredentials
InvalidChallengeResponse
UnsupportedChallengeMethod
UserInteractionNeeded
InternalError