Rotate an API key

JavaScript

import Cadenya from '@cadenya/cadenya';

const client = new Cadenya({
  apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted
});

const apiKey = await client.apiKeys.rotate('apikey_01HXKD2E5NQM3T9AYWCFCSPNQY', {
  workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q',
});

console.log(apiKey.metadata);

import os
from cadenya import Cadenya

client = Cadenya(
    api_key=os.environ.get("CADENYA_API_KEY"),  # This is the default and can be omitted
)
api_key = client.api_keys.rotate(
    id="apikey_01HXKD2E5NQM3T9AYWCFCSPNQY",
    workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
)
print(api_key.metadata)

package main

import (
	"context"
	"fmt"
	"go.cadenya.com/cadenya-go"
	"go.cadenya.com/cadenya-go/option"
)

func main() {
	client := cadenya.NewClient(
		option.WithAPIKey("My API Key"),
	)
	apiKey, err := client.APIKeys.Rotate(
		context.TODO(),
		"apikey_01HXKD2E5NQM3T9AYWCFCSPNQY",
		cadenya.APIKeyRotateParams{
			WorkspaceID: cadenya.String("workspace_01HXKD2E5NQM3T9AYWCF133E3Q"),
		},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", apiKey.Metadata)
}

require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

api_key = cadenya.api_keys.rotate(
  "apikey_01HXKD2E5NQM3T9AYWCFCSPNQY",
  workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
)

puts(api_key)

curl --request POST \
  --url https://api.cadenya.com/v1/workspaces/{workspaceId}/api_keys/{id}:rotate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cadenya.com/v1/workspaces/{workspaceId}/api_keys/{id}:rotate",
  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([
    
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

HttpResponse<String> response = Unirest.post("https://api.cadenya.com/v1/workspaces/{workspaceId}/api_keys/{id}:rotate")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();

{
  "metadata": {
    "id": "<string>",
    "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
    "name": "<string>",
    "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
    "externalId": "<string>",
    "labels": {},
    "createdAt": "2023-11-07T05:31:56Z"
  },
  "spec": {
    "token": "<string>",
    "description": "<string>",
    "permissions": [
      "<string>"
    ],
    "system": true
  },
  "info": {
    "createdBy": {
      "metadata": {
        "id": "<string>",
        "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
        "name": "<string>",
        "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
        "externalId": "<string>",
        "labels": {},
        "createdAt": "2023-11-07T05:31:56Z"
      },
      "spec": {
        "email": "<string>",
        "name": "<string>"
      }
    }
  }
}

{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "@type": "<string>"
    }
  ]
}

POST

workspaces

{workspaceId}

api_keys

{id}

:rotate

JavaScript

import Cadenya from '@cadenya/cadenya';

const client = new Cadenya({
  apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted
});

const apiKey = await client.apiKeys.rotate('apikey_01HXKD2E5NQM3T9AYWCFCSPNQY', {
  workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q',
});

console.log(apiKey.metadata);

import os
from cadenya import Cadenya

client = Cadenya(
    api_key=os.environ.get("CADENYA_API_KEY"),  # This is the default and can be omitted
)
api_key = client.api_keys.rotate(
    id="apikey_01HXKD2E5NQM3T9AYWCFCSPNQY",
    workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
)
print(api_key.metadata)

package main

import (
	"context"
	"fmt"
	"go.cadenya.com/cadenya-go"
	"go.cadenya.com/cadenya-go/option"
)

func main() {
	client := cadenya.NewClient(
		option.WithAPIKey("My API Key"),
	)
	apiKey, err := client.APIKeys.Rotate(
		context.TODO(),
		"apikey_01HXKD2E5NQM3T9AYWCFCSPNQY",
		cadenya.APIKeyRotateParams{
			WorkspaceID: cadenya.String("workspace_01HXKD2E5NQM3T9AYWCF133E3Q"),
		},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", apiKey.Metadata)
}

require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

api_key = cadenya.api_keys.rotate(
  "apikey_01HXKD2E5NQM3T9AYWCFCSPNQY",
  workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
)

puts(api_key)

curl --request POST \
  --url https://api.cadenya.com/v1/workspaces/{workspaceId}/api_keys/{id}:rotate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cadenya.com/v1/workspaces/{workspaceId}/api_keys/{id}:rotate",
  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([
    
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

HttpResponse<String> response = Unirest.post("https://api.cadenya.com/v1/workspaces/{workspaceId}/api_keys/{id}:rotate")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();

{
  "metadata": {
    "id": "<string>",
    "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
    "name": "<string>",
    "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
    "externalId": "<string>",
    "labels": {},
    "createdAt": "2023-11-07T05:31:56Z"
  },
  "spec": {
    "token": "<string>",
    "description": "<string>",
    "permissions": [
      "<string>"
    ],
    "system": true
  },
  "info": {
    "createdBy": {
      "metadata": {
        "id": "<string>",
        "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
        "name": "<string>",
        "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
        "externalId": "<string>",
        "labels": {},
        "createdAt": "2023-11-07T05:31:56Z"
      },
      "spec": {
        "email": "<string>",
        "name": "<string>"
      }
    }
  }
}

{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "@type": "<string>"
    }
  ]
}

Rotation swaps the credential under the key: same ID, same name, same scopes, new token. Every token the key issued before this call stops working the moment it returns.

const key = await client.apiKeys.rotate(apiKeyId, { workspaceId });

// The new token, shown this once. The old one is already dead.
console.log(key.spec.token);

key, err := client.APIKeys.Rotate(ctx, apiKeyID,
	cadenya.APIKeyRotateParams{WorkspaceID: cadenya.String(workspaceID)})
if err != nil {
	log.Fatal(err)
}

// The new token, shown this once. The old one is already dead.
log.Println(key.Spec.Token)

key = cadenya.api_keys.rotate(api_key_id, workspace_id: workspace_id)

# The new token, shown this once. The old one is already dead.
puts key.spec.token

curl -X POST "https://api.cadenya.com/v1/workspaces/${WORKSPACE_ID}/api_keys/${API_KEY_ID}:rotate" \
  -H "Authorization: Bearer ${CADENYA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{}'

Invalidation is immediate and covers every previous token, not only the latest. Any service still holding the old value starts failing auth on its next request, so update every consumer of the key as part of the same deploy, not after it.

Rotate is also the recovery path

Cadenya never shows a token after the response that minted it. Lost the value? There is nothing to look up, only this call: rotate, capture spec.token, and move on. That is the “lose it, rotate it” rule from the API key model.

Create an API key

The other response that carries a token.

Disable an API key

When you want the key off, not reissued.

Rotate the global API key

The same motion for the account-wide key.

Update an API key

Change scopes without touching the token.

Authorizations

Authorization

string

header

required

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

Path Parameters

workspaceId

string

required

The workspace the API key belongs to (path).

Example:

"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"

string

required

The API key to rotate. A new token is issued and any existing token is invalidated.

Example:

"apikey_01HXKD2E5NQM3T9AYWCFCSPNQY"

Body

application/json

The body is of type object.

Response

An API key. Every key belongs to exactly one workspace and is managed via the workspace-scoped API key routes. The only exception is the system-managed global account key, which spans all workspaces and is managed via the account global_api_key routes.

metadata

object

required

AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

Show child attributes

spec

object

required

Configuration for an API key.

Show child attributes

state

enum<string>

required

read-only

The current lifecycle state of the API key. Output only. Keys are created STATE_ENABLED; use the :disable and :enable actions to transition between states.

Available options:

STATE_UNSPECIFIED,

STATE_ENABLED,

STATE_DISABLED

info

object

Show child attributes

​Rotate is also the recovery path

​Related

Create an API key

Disable an API key

Rotate the global API key

Update an API key

Authorizations

Path Parameters

Body

Response

Rotate is also the recovery path

Related