API keys

Manage API keys for your organization. Keys control access to the Texture API and come in several types depending on your use case. For when to use each type, see Keys.

Key types#

API key object#

{
  "id": "key_abc123def456",
  "name": "Production Key",
  "type": "SERVER",
  "keyPrefix": "server_a1b2c3",
  "workspaceId": "ws_abc123def456",
  "ownerId": null,
  "revoked": false,
  "expiresAt": null,
  "createdAt": "2025-06-01T00:00:00.000Z"
}

List API keys#

GET /v1/api-keys

Query parameters:

Response: 200 OK — Paginated list of API key objects.

Get API key#

GET /v1/api-keys/:id

Response: 200 OK — Returns the API key object.

Create API key#

POST /v1/api-keys

Request body:

curl -X POST https://api.texturehq.com/v1/api-keys \
  -H "Texture-Api-Key: management_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"name": "CI/CD Key", "type": "SERVER"}'

import requests
 
resp = requests.post(
    "https://api.texturehq.com/v1/api-keys",
    headers={
        "Texture-Api-Key": "management_abc123...",
        "Content-Type": "application/json",
    },
    json={"name": "CI/CD Key", "type": "SERVER"},
)
print(resp.json())

const resp = await fetch("https://api.texturehq.com/v1/api-keys", {
  method: "POST",
  headers: {
    "Texture-Api-Key": "management_abc123...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "CI/CD Key", type: "SERVER" }),
});
const data = await resp.json();
console.log(data);

Response: 201 Created

{
  "id": "key_abc123def456",
  "name": "CI/CD Key",
  "type": "SERVER",
  "key": "server_a1b2c3d4e5f6g7h8i9j0k1l2",
  "workspaceId": "ws_abc123def456",
  "ownerId": null,
  "expiresAt": null,
  "createdAt": "2025-06-01T00:00:00.000Z"
}

Update API key#

PATCH /v1/api-keys/:id

Request body:

Response: 200 OK — Returns the updated API key object.

Revoke API key#

Permanently revoke an API key. This is irreversible — the key immediately stops working.

POST /v1/api-keys/:id/revoke

Response: 200 OK

{
  "message": "API key revoked"
}

Zero-downtime key rotation#

Rotating keys without downtime requires creating the new key before revoking the old one:

Step 1: Create the replacement key#

curl -X POST https://api.texturehq.com/v1/api-keys \
  -H "Texture-Api-Key: management_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Production Key (rotated 2025-06)", "type": "SERVER"}'

Save the key value from the response.

Step 2: Deploy the new key#

Update your application's configuration with the new key — environment variable, secrets manager, etc. Verify the new key is working before proceeding.

Step 3: Revoke the old key#

Only after confirming the new key is live and working:

curl -X POST https://api.texturehq.com/v1/api-keys/OLD_KEY_ID/revoke \
  -H "Texture-Api-Key: management_abc123..."

Step 4: Verify#

Check the Audit Log to confirm the revocation was recorded and no requests are still using the old key.

Security best practices#

Store keys securely#

• Use environment variables or a dedicated secrets manager (AWS Secrets Manager, HashiCorp Vault, Google Secret Manager, 1Password, Doppler).
• Never commit keys to version control. Add patterns like management_* and server_* to your .gitignore.
• Never expose keys in client-side code. Management and Server keys must only be used from backend services.

Principle of least privilege#

• Create separate keys for each environment (production, staging, CI/CD).
• Use the most restrictive key type for each use case — if you only need to read devices, use a SERVER key instead of a MANAGEMENT key.
• Revoke unused keys promptly. List your keys periodically and revoke any that are no longer needed.

Rotation policy#

• Rotate keys regularly — at minimum every 90 days for production keys.
• Rotate immediately if a key may have been exposed (accidentally committed, logged, or sent to an untrusted party).
• Audit key usage via the Audit Log to detect anomalous activity.

Incident response#

If a key is compromised:

1. Create a new key immediately via the Management API.
2. Deploy the new key to all systems.
3. Revoke the compromised key once the new key is confirmed working.
4. Review audit logs for any unauthorized actions during the exposure window.