Skip to main content
POST
/
api-keys
Create API key
curl --request POST \
  --url http://localhost:5001/api-keys \
  --header 'X-blnk-key: <api-key>'
import requests

url = "http://localhost:5001/api-keys"

headers = {"X-blnk-key": "<api-key>"}

response = requests.post(url, headers=headers)

print(response.text)
const options = {method: 'POST', headers: {'X-blnk-key': '<api-key>'}};

fetch('http://localhost:5001/api-keys', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "5001",
  CURLOPT_URL => "http://localhost:5001/api-keys",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "X-blnk-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

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

func main() {

	url := "http://localhost:5001/api-keys"

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

	req.Header.Add("X-blnk-key", "<api-key>")

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

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

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("http://localhost:5001/api-keys")
  .header("X-blnk-key", "<api-key>")
  .asString();
require 'uri'
require 'net/http'

url = URI("http://localhost:5001/api-keys")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["X-blnk-key"] = '<api-key>'

response = http.request(request)
puts response.read_body
Use blnk.api_keys.create to create a scoped API key.
1

Call the method

blnk.api_keys.create
response = blnk.api_keys.create({
  "name": "Service Account",
  "owner": "merchant_a",
  "scopes": ["ledgers:read", "balances:write"],
  "expires_at": "2026-12-31T23:59:59Z",
})
FieldTypeDescription
namestrDescriptive name for the key or service account.
ownerstrOwner identifier you assign, such as a team, service, or user ID.
scopesstring[]List of permissions in resource:action format (for example ledgers:read).
expires_atstrExpiration timestamp (ISO 8601, for example 2026-12-31T23:59:59Z).
2

Store the plaintext key

Save response.data["key"] immediately. It is only returned at creation and cannot be retrieved later.
3

Response

201 Created
{
  "api_key_id": "api_key_879f0ecb-e29f-4137-801b-1048366381db",
  "key": "YVLIhuIplUzLRCcT9r7DQ_jsGKCXAn39JQ3n_o-Ll2Q=",
  "name": "Service Account",
  "owner_id": "owner_id",
  "scopes": ["ledgers:read", "balances:write"],
  "expires_at": "2026-03-11T00:00:00Z",
  "created_at": "2025-11-18T13:39:50.390457762Z",
  "last_used_at": "0001-01-01T00:00:00Z",
  "is_revoked": false
}
FieldTypeDescription
api_key_idstrUnique ID for the key. Use it to revoke the key.
keystrPlaintext secret. Store it now. It is only returned at creation.
scopesstring[]Permissions granted to the key.
expires_atstrDate and time the key expires.
is_revokedboolWhether the key has been revoked.

How API keys work

Scopes, the master key, and the auth model.

Create API key

HTTP request and response schema.

​
Need help?

We are very happy to help you make the most of Blnk, regardless of whether it is your first time or you are switching from another tool. To ask questions or discuss issues, please contact us or join our Discord community.