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"},"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"},"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"
},
"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\"},\"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\"},\"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"
],
"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, streamline the linking flow, and provide enhanced debugging and improved privacy controls for your end user.
existing_link_id
: string
Supply the existing link_id if you are asking the user to reconnect or modify this link.
When reconnecting, if new accounts are discovered they will be presented to the user so permission to access them can be granted (or denied). Access to previously permitted accounts is not revokable at this point.
If necessary, MoneyKit may attempt to reconnect the account using a different provider than the link was originally connected through. The change in provider is generally seamless. MoneyKit normalizes incoming data to minimize provider-specific differences, and we deduplicate new transactions, so data continuity is generally assured; however, small discrepancies can still occur.
A reconnection cannot change the institution, the customer_user.id, or the country for an
existing link. These parameters will be silently ignored if existing_link_id is supplied.
New products can be added to an existing link. The user will be asked for permission for any added products. Existing product settings, however, cannot be changed and will be silently ignored.
The webhook for an existing link can be changed, and the existing webhook will be removed if
the webhook parameter is omitted, so you should supply the webhook URL if you want to receive
webhook events for the reconnected link.
Similarly, a reconnected link will be assigned whatever link_tags are supplied, and existing tags will
be removed if link_tags is omitted, so you should supply the link_tags you want the link to have, if any.
example: mk_eqkWN34UEoa2NxyALG8pcV
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
link_tags
: array
You can supply one or more arbitrary strings as tags to describe this link.
default: []
example: smoke_test
example: user_type:admin
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
link_session_token
: string
required
A unique token identifying this link session.
example: c7318ff7-257c-490e-8242-03a815b223b7
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
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"},"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"},"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"
},
"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\"},\"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\"},\"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"
],
"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
}