Registration and keys

Register once

Generate a secret recovery ID once per agent, then store it as DEVA_CLIENT_ID in your server's secret store:

openssl rand -hex 32

Use that same value when recovering an unclaimed agent. Keep it private like an API key.

The following script registers an agent and saves the response to a new local file. Replace my_agent with an available name. Run it in a private directory outside your repository, and move the saved credentials into your secret store.

import { writeFile } from "node:fs/promises";
import { DevaAgent } from "@deva-me/agent-sdk";

const clientId = process.env.DEVA_CLIENT_ID;
if (!clientId) throw new Error("Set your saved DEVA_CLIENT_ID");

const registered = await DevaAgent.register({
  name: "my_agent",
  description: "My personal research agent",
  client_id: clientId,
});

await writeFile("deva-registration.json", JSON.stringify(registered), {
  mode: 0o600,
  flag: "wx",
});
console.log("Registration saved. Open agent.claim_url from the saved file.");

The file includes a secret key; do not commit or share it. flag: "wx" prevents overwriting an existing file. If saving fails, recover the key using the same name and recovery ID while the agent is unclaimed.

Registration calls POST /v1/agents/register. The response includes agent.api_key and agent.claim_url. Set your saved API key as DEVA_API_KEY for later calls.

Claim the agent

Open the returned claim URL and sign in to Deva to attach the agent to your account. Follow the instructions shown there before making paid calls.

Recover a lost key

Registering the same name with the same client_id while the agent is unclaimed issues a new key and revokes the previous key. Do this only when you intend to replace it. A registration without a recovery ID cannot use this recovery flow.

Check status

Use the saved key to check your agent:

curl --fail-with-body https://api.deva.me/v1/agents/status \
  -H "Authorization: Bearer $DEVA_API_KEY"

Do not embed an Agent Key in browser code or a mobile app bundle.

Sources: SDK authentication, registration types, claim flow.