Create Link Session

Create Link Session

This endpoint is to be called by your back end, to establish a new link session for creating a link to your end user's institution.

URL

POST
/link-session
Request
curl --request POST \
--url https://api.moneykit.com/link-session \
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
--header 'content-type: application/json' \
--data '{"settings":{"providers":["moneykit"],"link_permissions":{"requested":[{"scope":"accounts","reason":"display your account balances","required":true}]},"products":{"account_numbers":{"required":false,"require_permission":false,"prefetch":false,"reason":"display your account balances"},"identity":{"required":false,"require_permission":false,"prefetch":false,"reason":"display your account balances"},"transactions":{"required":false,"require_permission":false,"prefetch":false,"reason":"display your account balances","extend_history":false},"investments":{"required":false,"require_permission":false,"prefetch":false,"reason":"display your account balances"}},"countries":["US"]},"customer_user":{"id":"string","email":{"address":"string","customer_verified_at":"2023-02-16T00:00:00"},"phone":{"number":"+16175551212","country":"US","customer_verified_at":"2023-02-16T00:00:00"}},"existing_link_id":"mk_eqkWN34UEoa2NxyALG8pcV","institution_id":"c7318ff7-257c-490e-8242-03a815b223b7","redirect_uri":"https://yourdomain.com/oauth.html","webhook":"https://yourdomain.com/moneykit_webhook","link_tags":["smoke_test","user_type:admin"],"connect_features":{}}'
const options = {
method: 'POST',
headers: {
Authorization: 'Bearer REPLACE_BEARER_TOKEN',
'content-type': 'application/json'
},
body: '{"settings":{"providers":["moneykit"],"link_permissions":{"requested":[{"scope":"accounts","reason":"display your account balances","required":true}]},"products":{"account_numbers":{"required":false,"require_permission":false,"prefetch":false,"reason":"display your account balances"},"identity":{"required":false,"require_permission":false,"prefetch":false,"reason":"display your account balances"},"transactions":{"required":false,"require_permission":false,"prefetch":false,"reason":"display your account balances","extend_history":false},"investments":{"required":false,"require_permission":false,"prefetch":false,"reason":"display your account balances"}},"countries":["US"]},"customer_user":{"id":"string","email":{"address":"string","customer_verified_at":"2023-02-16T00:00:00"},"phone":{"number":"+16175551212","country":"US","customer_verified_at":"2023-02-16T00:00:00"}},"existing_link_id":"mk_eqkWN34UEoa2NxyALG8pcV","institution_id":"c7318ff7-257c-490e-8242-03a815b223b7","redirect_uri":"https://yourdomain.com/oauth.html","webhook":"https://yourdomain.com/moneykit_webhook","link_tags":["smoke_test","user_type:admin"],"connect_features":{}}'
};

fetch('https://api.moneykit.com/link-session', options)
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
import requests

url = "https://api.moneykit.com/link-session"

payload = {
"settings": {
"providers": ["moneykit"],
"link_permissions": {"requested": [
{
"scope": "accounts",
"reason": "display your account balances",
"required": True
}
]},
"products": {
"account_numbers": {
"required": False,
"require_permission": False,
"prefetch": False,
"reason": "display your account balances"
},
"identity": {
"required": False,
"require_permission": False,
"prefetch": False,
"reason": "display your account balances"
},
"transactions": {
"required": False,
"require_permission": False,
"prefetch": False,
"reason": "display your account balances",
"extend_history": False
},
"investments": {
"required": False,
"require_permission": False,
"prefetch": False,
"reason": "display your account balances"
}
},
"countries": ["US"]
},
"customer_user": {
"id": "string",
"email": {
"address": "string",
"customer_verified_at": "2023-02-16T00:00:00"
},
"phone": {
"number": "+16175551212",
"country": "US",
"customer_verified_at": "2023-02-16T00:00:00"
}
},
"existing_link_id": "mk_eqkWN34UEoa2NxyALG8pcV",
"institution_id": "c7318ff7-257c-490e-8242-03a815b223b7",
"redirect_uri": "https://yourdomain.com/oauth.html",
"webhook": "https://yourdomain.com/moneykit_webhook",
"link_tags": ["smoke_test", "user_type:admin"],
"connect_features": {}
}
headers = {
"Authorization": "Bearer REPLACE_BEARER_TOKEN",
"content-type": "application/json"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)
package main

import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)

func main() {

url := "https://api.moneykit.com/link-session"

payload := strings.NewReader("{\"settings\":{\"providers\":[\"moneykit\"],\"link_permissions\":{\"requested\":[{\"scope\":\"accounts\",\"reason\":\"display your account balances\",\"required\":true}]},\"products\":{\"account_numbers\":{\"required\":false,\"require_permission\":false,\"prefetch\":false,\"reason\":\"display your account balances\"},\"identity\":{\"required\":false,\"require_permission\":false,\"prefetch\":false,\"reason\":\"display your account balances\"},\"transactions\":{\"required\":false,\"require_permission\":false,\"prefetch\":false,\"reason\":\"display your account balances\",\"extend_history\":false},\"investments\":{\"required\":false,\"require_permission\":false,\"prefetch\":false,\"reason\":\"display your account balances\"}},\"countries\":[\"US\"]},\"customer_user\":{\"id\":\"string\",\"email\":{\"address\":\"string\",\"customer_verified_at\":\"2023-02-16T00:00:00\"},\"phone\":{\"number\":\"+16175551212\",\"country\":\"US\",\"customer_verified_at\":\"2023-02-16T00:00:00\"}},\"existing_link_id\":\"mk_eqkWN34UEoa2NxyALG8pcV\",\"institution_id\":\"c7318ff7-257c-490e-8242-03a815b223b7\",\"redirect_uri\":\"https://yourdomain.com/oauth.html\",\"webhook\":\"https://yourdomain.com/moneykit_webhook\",\"link_tags\":[\"smoke_test\",\"user_type:admin\"],\"connect_features\":{}}")

req, _ := http.NewRequest("POST", url, payload)

req.Header.Add("Authorization", "Bearer REPLACE_BEARER_TOKEN")
req.Header.Add("content-type", "application/json")

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)

fmt.Println(res)
fmt.Println(string(body))

}
require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api.moneykit.com/link-session")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer REPLACE_BEARER_TOKEN'
request["content-type"] = 'application/json'
request.body = "{\"settings\":{\"providers\":[\"moneykit\"],\"link_permissions\":{\"requested\":[{\"scope\":\"accounts\",\"reason\":\"display your account balances\",\"required\":true}]},\"products\":{\"account_numbers\":{\"required\":false,\"require_permission\":false,\"prefetch\":false,\"reason\":\"display your account balances\"},\"identity\":{\"required\":false,\"require_permission\":false,\"prefetch\":false,\"reason\":\"display your account balances\"},\"transactions\":{\"required\":false,\"require_permission\":false,\"prefetch\":false,\"reason\":\"display your account balances\",\"extend_history\":false},\"investments\":{\"required\":false,\"require_permission\":false,\"prefetch\":false,\"reason\":\"display your account balances\"}},\"countries\":[\"US\"]},\"customer_user\":{\"id\":\"string\",\"email\":{\"address\":\"string\",\"customer_verified_at\":\"2023-02-16T00:00:00\"},\"phone\":{\"number\":\"+16175551212\",\"country\":\"US\",\"customer_verified_at\":\"2023-02-16T00:00:00\"}},\"existing_link_id\":\"mk_eqkWN34UEoa2NxyALG8pcV\",\"institution_id\":\"c7318ff7-257c-490e-8242-03a815b223b7\",\"redirect_uri\":\"https://yourdomain.com/oauth.html\",\"webhook\":\"https://yourdomain.com/moneykit_webhook\",\"link_tags\":[\"smoke_test\",\"user_type:admin\"],\"connect_features\":{}}"

response = http.request(request)
puts response.read_body
import Foundation

let headers = [
"Authorization": "Bearer REPLACE_BEARER_TOKEN",
"content-type": "application/json"
]
let parameters = [
"settings": [
"providers": ["moneykit"],
"link_permissions": ["requested": [
[
"scope": "accounts",
"reason": "display your account balances",
"required": true
]
]],
"products": [
"account_numbers": [
"required": false,
"require_permission": false,
"prefetch": false,
"reason": "display your account balances"
],
"identity": [
"required": false,
"require_permission": false,
"prefetch": false,
"reason": "display your account balances"
],
"transactions": [
"required": false,
"require_permission": false,
"prefetch": false,
"reason": "display your account balances",
"extend_history": false
],
"investments": [
"required": false,
"require_permission": false,
"prefetch": false,
"reason": "display your account balances"
]
],
"countries": ["US"]
],
"customer_user": [
"id": "string",
"email": [
"address": "string",
"customer_verified_at": "2023-02-16T00:00:00"
],
"phone": [
"number": "+16175551212",
"country": "US",
"customer_verified_at": "2023-02-16T00:00:00"
]
],
"existing_link_id": "mk_eqkWN34UEoa2NxyALG8pcV",
"institution_id": "c7318ff7-257c-490e-8242-03a815b223b7",
"redirect_uri": "https://yourdomain.com/oauth.html",
"webhook": "https://yourdomain.com/moneykit_webhook",
"link_tags": ["smoke_test", "user_type:admin"],
"connect_features": []
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.moneykit.com/link-session")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})

dataTask.resume()
Response
{
"link_session_token": "c7318ff7-257c-490e-8242-03a815b223b7"
}
{
"error_code": "api_error.auth.expired_access_token",
"error_message": "Access token expired",
"documentation_url": string
}
{
"error_code": "link_session_error.forbidden_config",
"error_message": "Forbidden use of a Connect feature",
"documentation_url": string
}

connect_features

: object

Enables optional testing and UI features.

customer_user

: object

required

Details about your end user. These details are used to improve conversion and streamline the linking flow, and to support the MoneyID system, which provides enhanced debugging and improved privacy controls for your end user.

institution_id

: string

The ID of the institution you want to link to. Providing this will skip the institution selection step. This field is ignored if existing_link_id is provided.

example: c7318ff7-257c-490e-8242-03a815b223b7

redirect_uri

: string

required

For Oauth linking, a URI indicating the destination, in your application, where the user should be sent after authenticating with the institution. The redirect_uri should not contain any query parameters, and it must be pre-approved by MoneyKit during the app setup process.

format:

uri

min length:

1

max length:

65536

example: https://yourdomain.com/oauth.html

settings

: object

If provided, these settings will override your default settings for this session.

webhook

: string

The destination URL to which any webhooks should be sent.

format:

uri

min length:

1

max length:

65536

example: https://yourdomain.com/moneykit_webhook

Responses

201

Successful Response

401

Invalid access_token or insufficent API client scope.

403

Forbidden session configuration.

error_code

: string

required

link_session_error.forbidden_config

default: "link_session_error.forbidden_config"

Allowed values:

"link_session_error.forbidden_config"

error_message

: string

required

Error message

example: Forbidden use of a Connect feature

documentation_url

: string

required