sessionKeys.create

namera.sessionKeys.create() register a local or 1Claw-managed session signer.

UsageCopy Anchor Link

Install @namera-ai/sdk and set NAMERA_API_KEY on your backend. IDs and responses below are illustrative fixtures; replace IDs with your own resources.

import { namera } from "./client";
const result = await namera.sessionKeys.create({
  namespace: "eip155",
  walletId: "0199dfe1-0000-7000-8000-000000000001",
  metadata: { version: 1, name: "Local agent" },
  signer: { custody: "namera-managed", provider: "1claw", algorithm: "secp256k1" },
  onchain: {
    installations: [
      {
        chainId: "eip155:11155111",
        validAfter: Math.floor(Date.now() / 1000),
        validUntil: Math.floor(Date.now() / 1000) + 3600,
        permissions: [{ type: "root" }],
        allowSignatures: false,
      },
    ],
  },
  policies: [],
});
if (!result.success) throw new Error(result.error.message);

console.log(result.data);

ReturnsCopy Anchor Link

API methods return a Promise<NameraResult<T, E>>. When success is true, data contains the value described below and error is null. On failure, data is null and error describes the failure.

The JSON example shows the complete successful data, with illustrative values. Date-time values use ISO strings in JSON; bigint values use decimal strings. See Handling Results and Errors for the error shape.

Returns the complete pending session, public signer, account, creator, and per-network installations. API-key creators use { type: "api-key", actorId, id, metadata }; human creators retain the member/user/role shape. This fixture uses root authority; choose narrower permissions for restricted agents.

{
  "id": "0199dfe1-0000-7000-8000-000000000003",
  "organizationId": "0199dfe1-0000-7000-8000-000000000006",
  "walletId": "0199dfe1-0000-7000-8000-000000000001",
  "signingKeyId": "0199dfe1-0000-7000-8000-000000000012",
  "namespace": "eip155",
  "metadata": {
    "version": 1,
    "name": "Local agent"
  },
  "policies": [],
  "policyHash": "9Z4ZzPfiQ4hIUpSXTY_nQ2E9-kjd2w_5wbLwIj7visI",
  "status": "pending",
  "revokedAt": null,
  "createdAt": "2026-10-15T02:39:05.307Z",
  "signer": {
    "custody": "namera-managed",
    "provider": "1claw",
    "algorithm": "secp256k1",
    "publicKey": "0x04e37a5065266fa599595e06a6968cdfe2d588cfbbbbb48f0d4c504048c53786a87ff061f472d579833ea98e99f425febabd2445a8760e225cb1e5b4a029cd18b8"
  },
  "wallet": {
    "id": "0199dfe1-0000-7000-8000-000000000001",
    "organizationId": "0199dfe1-0000-7000-8000-000000000006",
    "metadata": {
      "version": 1,
      "name": "Provisioned account"
    },
    "status": "active",
    "namespace": "eip155",
    "address": "0x3333333333333333333333333333333333333333",
    "owner": {
      "signingKeyId": "0199dfe1-0000-7000-8000-000000000008",
      "custody": "namera-managed",
      "provider": "1claw",
      "algorithm": "secp256k1"
    },
    "createdAt": "2026-10-15T02:39:05.250Z",
    "updatedAt": "2026-10-15T02:39:05.250Z",
    "implementation": "alchemy-modular-v2",
    "data": {
      "version": 1,
      "modularAccountVersion": "2.0.0",
      "validatorType": "ecdsa_secp256k1",
      "entryPointVersion": "0.7",
      "accountMode": "factory",
      "factoryVersion": "2.0.0",
      "implementationVersion": "v1.0.0",
      "ownerAddress": "0x52e7f17258368d7f9Ebd7bDf8d6869Bc4759aBA1",
      "salt": "0"
    }
  },
  "creator": {
    "type": "api-key",
    "actorId": "0199dfe1-0000-7000-8000-000000000009",
    "id": "0199dfe1-0000-7000-8000-000000000010",
    "metadata": {
      "version": 1,
      "name": "Workspace backend"
    }
  },
  "installations": [
    {
      "id": "0199dfe1-0000-7000-8000-000000000013",
      "chainId": "eip155:11155111",
      "status": "pending",
      "authorization": {
        "version": 1,
        "entityId": 142534698,
        "signerAddress": "0x7838CE7D0AC8943A2fAA4e8ab8ae901b05eA7A03",
        "permissions": [
          {
            "type": "root"
          }
        ],
        "allowSignatures": false,
        "validAfter": 1792031945,
        "validUntil": 1792035545
      },
      "installTransactionHash": null,
      "uninstallTransactionHash": null
    }
  ]
}

ParametersCopy Anchor Link

namespaceCopy Anchor Link

Type: "eip155". Required. The implemented chain namespace.

import { namera } from "./client";
const result = await namera.sessionKeys.create({
  namespace: "eip155", 
  walletId: "0199dfe1-0000-7000-8000-000000000001",
  metadata: { version: 1, name: "Local agent" },
  signer: { custody: "namera-managed", provider: "1claw", algorithm: "secp256k1" },
  onchain: {
    installations: [
      {
        chainId: "eip155:11155111",
        validAfter: Math.floor(Date.now() / 1000),
        validUntil: Math.floor(Date.now() / 1000) + 3600,
        permissions: [{ type: "root" }],
        allowSignatures: false,
      },
    ],
  },
  policies: [],
});
if (!result.success) throw new Error(result.error.message);

console.log(result.data);

walletIdCopy Anchor Link

Type: string. Required. Existing account UUID in the same workspace. Account ownership and session custody are independent.

import { namera } from "./client";
const result = await namera.sessionKeys.create({
  namespace: "eip155",
  walletId: "0199dfe1-0000-7000-8000-000000000001", 
  metadata: { version: 1, name: "Local agent" },
  signer: { custody: "namera-managed", provider: "1claw", algorithm: "secp256k1" },
  onchain: {
    installations: [
      {
        chainId: "eip155:11155111",
        validAfter: Math.floor(Date.now() / 1000),
        validUntil: Math.floor(Date.now() / 1000) + 3600,
        permissions: [{ type: "root" }],
        allowSignatures: false,
      },
    ],
  },
  policies: [],
});
if (!result.success) throw new Error(result.error.message);

console.log(result.data);

metadataCopy Anchor Link

Type: object. Required. Session display metadata: version: 1, a required name, and optional description and logo.

import { namera } from "./client";
const result = await namera.sessionKeys.create({
  namespace: "eip155",
  walletId: "0199dfe1-0000-7000-8000-000000000001",
  metadata: { version: 1, name: "Local agent" }, 
  signer: { custody: "namera-managed", provider: "1claw", algorithm: "secp256k1" },
  onchain: {
    installations: [
      {
        chainId: "eip155:11155111",
        validAfter: Math.floor(Date.now() / 1000),
        validUntil: Math.floor(Date.now() / 1000) + 3600,
        permissions: [{ type: "root" }],
        allowSignatures: false,
      },
    ],
  },
  policies: [],
});
if (!result.success) throw new Error(result.error.message);

console.log(result.data);

signerCopy Anchor Link

Type: object. Required. Use { custody: "namera-managed", provider: "1claw", algorithm: "secp256k1" }, or { custody: "local", algorithm: "secp256k1", publicKey }. The local public key must be uncompressed, beginning with 0x04 and containing 65 bytes. Keep the corresponding private key in your application’s secure signer store.

import { namera } from "./client";
const result = await namera.sessionKeys.create({
  namespace: "eip155",
  walletId: "0199dfe1-0000-7000-8000-000000000001",
  metadata: { version: 1, name: "Local agent" },
  signer: { custody: "namera-managed", provider: "1claw", algorithm: "secp256k1" }, 
  onchain: {
    installations: [
      {
        chainId: "eip155:11155111",
        validAfter: Math.floor(Date.now() / 1000),
        validUntil: Math.floor(Date.now() / 1000) + 3600,
        permissions: [{ type: "root" }],
        allowSignatures: false,
      },
    ],
  },
  policies: [],
});
if (!result.success) throw new Error(result.error.message);

console.log(result.data);

onchainCopy Anchor Link

Type: object. Required. Contains at least one installation; each network may appear once.

import { namera } from "./client";
const result = await namera.sessionKeys.create({
  namespace: "eip155",
  walletId: "0199dfe1-0000-7000-8000-000000000001",
  metadata: { version: 1, name: "Local agent" },
  signer: { custody: "namera-managed", provider: "1claw", algorithm: "secp256k1" },
  onchain: {
    installations: [
      {
        chainId: "eip155:11155111",
        validAfter: Math.floor(Date.now() / 1000),
        validUntil: Math.floor(Date.now() / 1000) + 3600,
        permissions: [{ type: "root" }],
        allowSignatures: false,
      },
    ],
  },
  policies: [],
});
if (!result.success) throw new Error(result.error.message);

console.log(result.data);

onchain.installationsCopy Anchor Link

Type: readonly object[]. Required. Each entry specifies chainId (a supported CAIP-2 network ID), validAfter and validUntil (Unix seconds), permissions (onchain permission definitions), and optional allowSignatures (defaults to false). Expiry must follow the start time and remain in the future at admission. Amount allowances are bigint values in token base units. root grants unrestricted account authority and cannot be combined with other permissions.

onchain.installations[].chainIdCopy Anchor Link

Type: SupportedEvmChainId. Required. The supported CAIP-2 network, such as eip155:11155111. Each network may appear once.

onchain.installations[].validAfterCopy Anchor Link

Type: number. Required. Nonnegative Unix timestamp in seconds at which transaction authority begins.

onchain.installations[].validUntilCopy Anchor Link

Type: number. Required. Unix timestamp in seconds after validAfter, still in the future at admission. Each network has its own expiry.

onchain.installations[].permissionsCopy Anchor Link

Type: readonly EvmSessionPermission[]. Required and nonempty. Choose onchain permissions such as native-token or ERC-20 allowances, allowed contracts/functions, and gas limits. Allowances are bigint base-unit amounts, not token display units. Root authority is exclusive and unrestricted. See Permissions.

onchain.installations[].allowSignaturesCopy Anchor Link

Type: boolean. Optional; defaults to false. Enables onchain ERC-1271 signature authority. Transaction spending and time hooks do not constrain existing signature authority; uninstall it to remove that authority onchain. Namera signing also requires an API signature policy.

policiesCopy Anchor Link

Type: readonly object[]. Required. Session-level API signature policies. An empty array adds no API signature policy; transaction authority comes from installed onchain permissions. Signature use additionally requires explicit onchain signature authority.

import { namera } from "./client";
const result = await namera.sessionKeys.create({
  namespace: "eip155",
  walletId: "0199dfe1-0000-7000-8000-000000000001",
  metadata: { version: 1, name: "Local agent" },
  signer: { custody: "namera-managed", provider: "1claw", algorithm: "secp256k1" },
  onchain: {
    installations: [
      {
        chainId: "eip155:11155111",
        validAfter: Math.floor(Date.now() / 1000),
        validUntil: Math.floor(Date.now() / 1000) + 3600,
        permissions: [{ type: "root" }],
        allowSignatures: false,
      },
    ],
  },
  policies: [], 
});
if (!result.success) throw new Error(result.error.message);

console.log(result.data);

policies[].type and policies[].versionCopy Anchor Link

Type: "evm.signature" | "evm.time-window" | "evm.chain-allowlist", and 1. Required for each policy. Each policy type may appear once. Creation accepts configuration only; persisted id and appliesTo fields are assigned by Namera.

policies[].allowedTypes and policies[].typedDataRulesCopy Anchor Link

Required for evm.signature: allowedTypes is a nonempty unique array of "message" and/or "typed-data". Optional typedDataRules is a nonempty array of rules with chainId, verifyingContract, and nonempty unique primaryTypes; name and version optionally restrict the typed-data domain. Omit rules to allow all typed data when that signature type is enabled. Rules constrain Namera requests, not direct signing with a caller-held key.

policies[].startsAt and policies[].expiresAtCopy Anchor Link

Required for evm.time-window. SDK values are DateTime.Utc | null for startsAt and DateTime.Utc for expiresAt; wire values are ISO date-time strings. Null start means no lower time bound. Expiry must follow a non-null start and remain in the future at admission. This policy restricts API signatures, not installed transaction authority.

policies[].chainIdsCopy Anchor Link

Required for evm.chain-allowlist: a nonempty unique array of supported CAIP-2 network IDs on which API signing is permitted. A chain allowlist does not itself grant signature authority.

Behavior and errorsCopy Anchor Link

Requires session-key:create and applies to any account in the API key’s workspace. Local signers submit only a public key. Managed signers provision a dedicated 1Claw key; never submit provider credentials. Creation atomically grants the calling API-key actor access to the new session. The session and installations remain pending until explicit owner-approved installation is confirmed. Managed creation retries transient failures with an SDK-generated idempotency key. Local registration is not automatically retried; retain your signer if a response is lost. No private key is returned. NETWORK_PAUSED, billing limits, invalid permissions, duplicate signers, and expired validity windows can reject creation.