Create API Key - DialNexa Documentation

POST

api-keys

Create a new API key for an organization

curl --request POST \
  --url https://api.dialnexa.com/api-keys \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "name": "Docs Key",
  "expire_now": false
}
'

import requests

url = "https://api.dialnexa.com/api-keys"

payload = {
    "name": "Docs Key",
    "expire_now": False
}
headers = {
    "x-organization-id": "<x-organization-id>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-organization-id': '<x-organization-id>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({name: 'Docs Key', expire_now: false})
};

fetch('https://api.dialnexa.com/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_URL => "https://api.dialnexa.com/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_POSTFIELDS => json_encode([
    'name' => 'Docs Key',
    'expire_now' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-organization-id: <x-organization-id>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.dialnexa.com/api-keys"

	payload := strings.NewReader("{\n  \"name\": \"Docs Key\",\n  \"expire_now\": false\n}")

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

	req.Header.Add("x-organization-id", "<x-organization-id>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.dialnexa.com/api-keys")
  .header("x-organization-id", "<x-organization-id>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Docs Key\",\n  \"expire_now\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.dialnexa.com/api-keys")

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

request = Net::HTTP::Post.new(url)
request["x-organization-id"] = '<x-organization-id>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Docs Key\",\n  \"expire_now\": false\n}"

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

Legacy endpoint - deprecated. Unversioned endpoints are scheduled for removal on July 31, 2026. A public v1 replacement is not currently listed in the v1 reference. This endpoint remains available for existing integrations until then.

Generates a new API key. The secret value is returned only once: in the response of this call. DialNexa does not store the secret in a recoverable form, so if you lose it you must revoke the key with Revoke API Key and create a new one. Keys are scoped to the workspace they are created in and inherit the permissions of the caller that created them.

When to use this

First-time setup: issue the initial key for a new environment.
New consumer service: issue a dedicated key for each upstream service so you can revoke them independently if needed.
Planned rotation: issue the next key as the first step in the Key rotation playbook.
Environment separation: keep production, staging, and development keys distinct so a leak in one environment does not compromise the others.

Best practices

One key per environment. Create separate keys for development, staging, and production so revocation never takes down more than one environment at a time.
One key per consumer service. If multiple services share a key, a leak forces you to rotate every consumer at once. Per-service keys narrow the blast radius.
Never commit keys to source control. Use environment variables or a secrets manager. Keys accidentally pushed to a public repository should be revoked immediately, even if you delete the commit.
Rotate periodically. Issue a new key, deploy it everywhere it is needed, verify traffic on the new key through List API Keys’ last_used_at field, then revoke the old one.

Authentication

Use the returned secret as a Bearer token in the Authorization header on every API request:

curl https://api.dialnexa.com/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY"

Errors

400 Bad Request is returned when the name field is missing or empty.
403 Forbidden is returned when the caller does not have permission to create API keys.

List API Keys: review every key on the workspace.
Rename API Key: change a key’s display name.
Revoke API Key: permanently retire a key.
Key rotation: recommended sequence for rotating keys without downtime.
Authentication: how keys are sent and verified.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

x-organization-id

string

required

RSA encrypted organization ID (base64 format)

Example:

"BASE64_ENCRYPTED_ORG_ID_HERE"

Body

application/json

name

string

required

Label for the API key

Example:

"Docs Key"

expire_now

boolean

Expire previous key immediately if true, else in 24 hours

Example:

false

Response

201 - application/json

API key created

List API KeysRetrieve every API key registered on your workspace, with metadata and last-used timestamps. Secrets are never returned.

Create a new API key for an organization

curl --request POST \
  --url https://api.dialnexa.com/api-keys \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "name": "Docs Key",
  "expire_now": false
}
'

import requests

url = "https://api.dialnexa.com/api-keys"

payload = {
    "name": "Docs Key",
    "expire_now": False
}
headers = {
    "x-organization-id": "<x-organization-id>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-organization-id': '<x-organization-id>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({name: 'Docs Key', expire_now: false})
};

fetch('https://api.dialnexa.com/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_URL => "https://api.dialnexa.com/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_POSTFIELDS => json_encode([
    'name' => 'Docs Key',
    'expire_now' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-organization-id: <x-organization-id>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.dialnexa.com/api-keys"

	payload := strings.NewReader("{\n  \"name\": \"Docs Key\",\n  \"expire_now\": false\n}")

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

	req.Header.Add("x-organization-id", "<x-organization-id>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.dialnexa.com/api-keys")
  .header("x-organization-id", "<x-organization-id>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Docs Key\",\n  \"expire_now\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.dialnexa.com/api-keys")

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

request = Net::HTTP::Post.new(url)
request["x-organization-id"] = '<x-organization-id>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Docs Key\",\n  \"expire_now\": false\n}"

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

​When to use this

​Best practices

​Authentication

​Errors

​Related endpoints

Authorizations

Headers

Body

Response

When to use this

Best practices

Authentication

Errors

Related endpoints