Fullmakt

Create an agent principal — the identity a fullmakt is brokered onto

Fullmakt Rails identity step. Creates an agent principal for the calling consumer: the agent_principal_id that POST /api/v1/fullmakt/request binds a systembruker delegation onto and POST /api/v1/fullmakt/revoke retires. A principal is a label the consumer declares for one of its own agents (display_name, plus an optional list of the Altinn scopes it is intended to carry), anchored to Apier's Altinn vendor system id. It is NOT a verified identity and is never presented as one: it holds no authority of its own, starts pending with no systembruker bound, and becomes an actor only once a fullmakt is brokered onto it and the company's signing authority approves that delegation inside Altinn. The write is a LOCAL service-role insert plus an immutable agent_principal.create audit_log row — no government call is made. Scope: the assignable fullmakt:write scope (the same one the request and revoke operations take), chosen at key creation; the default read:* key is refused with 403 SCOPE_INSUFFICIENT. Creation is capped per consumer per hour (429 RATE_LIMITED with Retry-After) on top of the per-key rate limit. Supports Idempotency-Key: a replay with the same key and body returns the stored 201 instead of a second principal. Norwegian term: «agentidentitet» (the code name agent_principal_id is unchanged).

post/api/v1/fullmakt/principals

Request

Base URL: https://www.apier.no
URL: https://www.apier.no/api/v1/fullmakt/principals
Auth: HTTP bearer

Headers

Idempotency-Keystring

Optional client-chosen key that makes this write safely retriable. When the same key is presented on a subsequent request with the same body, the gateway returns the original response (with Idempotent-Replay: true) instead of re-executing the write. Reservation is scoped to (consumer, endpoint, key) so the same key on different endpoints or different consumers does not collide. TTL: 24 hours. The key must be 1–255 printable ASCII characters — a v4 UUID or ULID is the recommended format. Keys are SHA-256 hashed before storage so they may safely carry client-internal identifiers.

X-Agent-Vendorstring

OPTIONAL forensic-only attestation: the agent vendor / framework that issued this request (e.g. anthropic, openai, langchain). Persisted to audit_log.agent_vendor and mcp_query_log.agent_vendor; never used for authorization, scope, rate-limit, or idempotency decisioning. The server strips ASCII control chars (0x00–0x1F + 0x7F), Unicode NEL / line / paragraph separators, and BOM before persistence; values exceeding 64 UTF-8 BYTES are byte-boundary clamped (a non-ASCII string declared at 64 chars may exceed the 64-byte ceiling and be clamped further). NEVER echoed in any response body, response header, _meta block, error message, or Sentry payload — one-way capture. Omitting this header writes SQL NULL to the persisted columns. The MCP transport equivalent is clientInfo.attestation.vendor.

X-Agent-Modelstring

OPTIONAL forensic-only attestation: the agent model id (e.g. claude-opus-4-7, gpt-4o-mini-2024-07-18). Persisted to audit_log.agent_model and mcp_query_log.agent_model; identical sanitisation + clamp + non-echo rules as X-Agent-Vendor (control-char strip, 128-UTF-8-BYTE ceiling, never visible on any response). Forensic-only: never used for authorization, scope, rate-limit, or idempotency decisioning.

X-Agent-Run-Idstring

OPTIONAL forensic-only attestation: an opaque agent-side run / trace identifier (e.g. a LangSmith run id, a vendor-specific session id). Persisted to audit_log.agent_run_id and mcp_query_log.agent_run_id; identical sanitisation + clamp + non-echo rules as X-Agent-Vendor (control-char strip, 256-UTF-8-BYTE ceiling, never visible on any response). Forensic-only: never used for authorization, scope, rate-limit, or idempotency decisioning.

Request body

display_namestring required

Human-readable label for the agent this principal represents (shown back on fullmakt status and receipts). 1–200 characters; stored verbatim. Not an identity claim — Apier verifies nothing about the agent behind it.

scopesstring[]

Optional. The Altinn scopes this principal is INTENDED to carry, recorded on the row and the audit trail as a declared intent. Omitted means no intent is recorded (an empty list is stored) — the scopes actually brokered are the ones sent to POST /api/v1/fullmakt/request. Each entry must contain a non-whitespace character; duplicates are rejected (400 VALIDATION_FAILED).

Example request

{
  "display_name": "Regnskaps-agenten",
  "scopes": [
    "altinn:accessmanagement/authorizedparties.read"
  ]
}

Response

Principal created. data.agent_principal.status is pending and system_user_id is null until a fullmakt is brokered onto it. Carries the standard _meta trust metadata, the X-Correlation-ID header and Cache-Control: no-store (a write endpoint is never cached).

successtrue required

Example response

{
  "data": {
    "agent_principal": {
      "id": "22222222-2222-4222-8222-222222222222",
      "display_name": "Regnskaps-agenten",
      "status": "pending",
      "scopes": [
        "altinn:accessmanagement/authorizedparties.read"
      ],
      "created_at": "2026-10-15T08:00:00.000Z"
    }
  },
  "_meta": {
    "rulebook_version": "v1.0.0",
    "source": "apier.no",
    "data_source": "Brønnøysund Enhetsregisteret + Apier Universal Rulebook",
    "schema_version": "1.0.0",
    "legal_basis": "NLOD — public registry reuse",
    "response_timestamp": "2026-04-24T12:00:00.000Z",
    "response_hash": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "source_snapshot_id": "brreg-2026-04-24T02:00:00.000Z",
    "cost_nok": 0.5,
    "wallet_remaining_nok": 9.5,
    "spend_cap_remaining_nok": 12.5
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.