Skip to main content

interfaces_b93.go (package eai)

Source: sdks/go/interfaces_b93.go. Back to the Go SDK reference index.

note

This page is generated by tools/docs/gen_sdk_reference.py from the SDK sources and the OpenAPI text folders. Do not edit it by hand: change the source and regenerate.

Model AssumeRequest​

AssumeRequest is the body of POST /v1/service-identities/{identity_id}/assume.

Fields:

NameTypeRequiredDescription
Purpose (purpose)stringyesPurpose is required (3 to 500 characters) and lands in the signed context and the audit trail.
Audience (audience)[]stringnoAudience defaults to the service itself on the server side.
TTLSeconds (ttl_seconds)intnoTTLSeconds is 30 to 3600; zero keeps the server default (900).
Scopes (scopes)[]stringnoScopes defaults to the identity scopes, never beyond the caller's.

Model AuthzCheck​

AuthzCheck is one relation check of POST /v1/authz/check.

Fields:

NameTypeRequiredDescription
Subject (subject)stringyesSubject whose access is checked (subject).
Relation (relation)stringyesRelation to check between the subject and the object (relation).
Object (object)stringyesObject checked, <type>:<id>, for example project:42.

Model AuthzResult​

AuthzResult is the confirmed answer of one check.

Fields:

NameTypeRequiredDescription
AuthzCheckembeddedyesThe check that was sent, embedded: Subject, Relation, Object.
Allowed (allowed)boolyesDecision of the server, read from an explicit boolean allowed; never a default allow.
Engine (engine)stringyesAuto (default), HPA or KEDA.

Class Span​

Span is a client side span; EndSpan sends it to POST /v1/telemetry/spans.

Fields:

NameTypeRequiredDescription
TraceIDstringyesTrace identifier, 32 random hex characters when StartSpan got none.
SpanIDstringyesRandom 16 hex character span identifier.
ParentSpanIDstringyesIdentifier of the parent span, empty for a root span.
NamestringyesName of the span.
Starttime.TimeyesStart time of the span, in UTC.
Attributesmap[string]anyyesAttributes of the span, sent with EndSpan; never nil after StartSpan.

Span.RecordEvent​

RecordEvent(name string, attributes map[string]any)

RecordEvent adds a timestamped event to the span.

NameTypeDefaultRequiredDescription
namestringyesName of the event.
attributesmap[string]anyyesAttributes of the event.

Class ServiceIdentitiesService​

ServiceIdentitiesService groups the endpoints of: Service identities (SPIFFE ids).

ServiceIdentitiesService.AssumeService​

AssumeService(ctx context.Context, identityID string, req AssumeRequest, opts ...CallOption) (json.RawMessage, error)

Assume a service identity. Returns a signed, short lived ExecutionContext whose subject is the service identity, for the caller. It is not an API credential: downstream services verify it (POST /v1/context/verify or the JWKS) and the caller revokes it with POST /v1/context/{context_id}/revoke.

Route: /v1/service-identities/{identity_id}/assume (POST).

NameTypeDefaultRequiredDescription
ctxcontext.ContextyesContext of the call: cancellation and deadline.
identityIDstringyesIdentifier (UUID) of the service identity.
reqAssumeRequestyesPurpose, audiences, lifetime and scopes of the requested context.
opts...CallOptionnoPer call options (query, idempotency key, traceparent, headers).

Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Assume a service identity". The error is a typed error of the SDK, nil on success.

Raises: error, the typed errors of the transport (Errors).

ServiceIdentitiesService.Current​

Current(ctx context.Context, opts ...CallOption) (json.RawMessage, error)

Show the calling identity. Returns the identity the platform resolved for this request, whatever the credential (OIDC token, portal session, API key, SPIFFE): id, kind (user, service, agent, system), tenant_id, tenant_slug, roles, scopes, clearance, auth_method and display. Read only, open to any authenticated caller, also while a local account must still change its password. Use it to check a new token or key.

Route: /v1/identity/whoami (GET).

NameTypeDefaultRequiredDescription
ctxcontext.ContextyesContext of the call: cancellation and deadline.
opts...CallOptionnoPer call options (query, idempotency key, traceparent, headers).

Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Show the calling identity". The error is a typed error of the SDK, nil on success.

Raises: error, the typed errors of the transport (Errors).

ServiceIdentitiesService.Verify​

Verify(ctx context.Context, token string, audience string, opts ...CallOption) (json.RawMessage, error)

Verify a signed execution context. Checks a token and returns valid, context_id, kid, alg, the claims and the context document. Checks, in order: structure and canonical form (context_malformed), algorithm and signature (context_invalid_signature), known non revoked key (context_unknown_key), issuer (context_wrong_issuer), audience (context_wrong_audience), lifetime (context_expired), tenant of the caller (403 context_tenant_mismatch), issuance record (context_revoked), digest of the document and delegation chain (a revoked delegation gives context_revoked). Refusals answer 401 unless stated and are audited; a success binds the verified identity to the audit events of the request.

Route: /v1/context/verify (POST).

NameTypeDefaultRequiredDescription
ctxcontext.ContextyesContext of the call: cancellation and deadline.
tokenstringyesThe JWS compact token (10 to 65536 characters).
audiencestringyesAudience the verifier expects (up to 200 characters). Default: the first platform audience.
opts...CallOptionnoPer call options (query, idempotency key, traceparent, headers).

Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Verify a signed execution context". The error is a typed error of the SDK, nil on success.

Raises: error, the typed errors of the transport (Errors).

Class AuthzService​

AuthzService groups the endpoints of: Relationship based authorization (OpenFGA or builtin).

AuthzService.Allowed​

Allowed(ctx context.Context, check AuthzCheck, opts ...CallOption) (AuthzResult, error)

Check a relation. Tells whether subject holds relation on object, following inheritance. Up to 20 contextual_tuples are taken as true for this check only and never stored (an invalid one answers 422 validation_error). Open to any member of the tenant. The answer gives allowed, engine, subject, relation and object. Writes the audit event authz.check with the decision. When the engine cannot answer, the decision is a refusal, it is audited and the API answers 502 authz_backend_error.

Route: /v1/authz/check (POST).

NameTypeDefaultRequiredDescription
ctxcontext.ContextyesContext of the call: cancellation and deadline.
checkAuthzCheckyesSubject, relation and object to check.
opts...CallOptionnoPer call options (query, idempotency key, traceparent, headers).

Returns: (AuthzResult, error). A AuthzResult: AuthzResult is the confirmed answer of one check. The error is a typed error of the SDK, nil on success.

Raises: error, the typed errors of the transport (Errors).

AuthzService.CheckBatch​

CheckBatch(ctx context.Context, checks []AuthzCheck, opts ...CallOption) ([]AuthzResult, error)

Check a relation. Tells whether subject holds relation on object, following inheritance. Up to 20 contextual_tuples are taken as true for this check only and never stored (an invalid one answers 422 validation_error). Open to any member of the tenant. The answer gives allowed, engine, subject, relation and object. Writes the audit event authz.check with the decision. When the engine cannot answer, the decision is a refusal, it is audited and the API answers 502 authz_backend_error.

Route: /v1/authz/check (POST).

NameTypeDefaultRequiredDescription
ctxcontext.ContextyesContext of the call: cancellation and deadline.
checks[]AuthzCheckyesChecks run one after the other; the first error stops the batch.
opts...CallOptionnoPer call options (query, idempotency key, traceparent, headers).

Returns: ([]AuthzResult, error). A AuthzResult: AuthzResult is the confirmed answer of one check. The error is a typed error of the SDK, nil on success.

Raises: error, the typed errors of the transport (Errors).

AuthzService.Explain​

Explain(ctx context.Context, body any, opts ...CallOption) (json.RawMessage, error)

Authorize an action under a delegation. Computes the effective permission of an action: user AND agent AND delegation AND resource restriction AND relationship (OpenFGA or the builtin tuples) AND policy (OPA or builtin). Give delegation_id, or run_id to use the delegation of a run (400 invalid_request without either; 403 delegation_required for a run without delegation).

Route: /v1/delegations/authorize (POST).

NameTypeDefaultRequiredDescription
ctxcontext.ContextyesContext of the call: cancellation and deadline.
bodyanyyesAction, delegation or run, and the scope, resource, relation, audience and classification to check.
opts...CallOptionnoPer call options (query, idempotency key, traceparent, headers).

Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Authorize an action under a delegation". The error is a typed error of the SDK, nil on success.

Raises: error, the typed errors of the transport (Errors).

Class ToolsService​

ToolsService groups the endpoints of: Tool registry and Tool Gateway invocations.

ToolsService.Discover​

Discover(ctx context.Context, opts ...CallOption) (*Page, error)

List the tools. Tools of the tenant in name order, optionally with one status. One page only.

Route: /v1/tools (GET).

NameTypeDefaultRequiredDescription
ctxcontext.ContextyesContext of the call: cancellation and deadline.
opts...CallOptionnoPer call options (query, idempotency key, traceparent, headers).

Returns: (*Page, error). A Page: Page is one page of a cursor paginated collection {"items": [...], "next_cursor": "..."|null}. The error is a typed error of the SDK, nil on success.

Raises: error, the typed errors of the transport (Errors).

ToolsService.Validate​

Validate(ctx context.Context, invocation any, opts ...CallOption) (json.RawMessage, error)

Validate a document against a contract. Validates the body against the contract, formats included, without storing anything. The answer gives contract, valid and errors, each with the JSON path of the faulty value and a message. Open to any authenticated caller. An unknown contract answers 404 unknown_contract.

Route: /v1/contracts/{name}/validate (POST).

NameTypeDefaultRequiredDescription
ctxcontext.ContextyesContext of the call: cancellation and deadline.
invocationanyyesTool Invocation document to check against the tool-invocation contract on the server.
opts...CallOptionnoPer call options (query, idempotency key, traceparent, headers).

Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Validate a document against a contract". The error is a typed error of the SDK, nil on success.

Raises: error, the typed errors of the transport (Errors).

Class PrivacyService​

Privacy and data protection. Data protection services of the tenant: classification, DLP (data loss prevention), tokenization and envelope encryption.

PrivacyService.Detect​

Detect(ctx context.Context, body any, opts ...CallOption) (json.RawMessage, error)

Inspect a text for sensitive data. Runs DLP on the text with the tenant rules, in mode detect unless mode says otherwise. The answer gives text, findings (type, position, score, classification, short preview, action, rule), action (strongest action applied), classification, mode, engine (builtin or presidio), blocked and count. An unknown mode answers 400. Open to any member of the tenant. Writes the audit event dlp.inspect (counts and types only).

Route: /v1/dlp/inspect (POST).

NameTypeDefaultRequiredDescription
ctxcontext.ContextyesContext of the call: cancellation and deadline.
bodyanyyesText, optional mode and language.
opts...CallOptionnoPer call options (query, idempotency key, traceparent, headers).

Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Inspect a text for sensitive data". The error is a typed error of the SDK, nil on success.

Raises: error, the typed errors of the transport (Errors).

PrivacyService.Detokenize​

Detokenize(ctx context.Context, body any, opts ...CallOption) (json.RawMessage, error)

Detokenize values. Returns the original values of tokens given in tokens or found in text.

Route: /v1/tokenization/detokenize (POST).

NameTypeDefaultRequiredDescription
ctxcontext.ContextyesContext of the call: cancellation and deadline.
bodyanyyesTokens or text holding tokens, and purpose.
opts...CallOptionnoPer call options (query, idempotency key, traceparent, headers).

Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Detokenize values". The error is a typed error of the SDK, nil on success.

Raises: error, the typed errors of the transport (Errors).

PrivacyService.Encrypt​

Encrypt(ctx context.Context, body any, opts ...CallOption) (json.RawMessage, error)

Encrypt data with a tenant key. Encrypts plaintext (UTF-8 text) or plaintext_base64 (bytes) with the current version of the key, bound to aad. Returns ciphertext (eaienc1:...), key_id and key_version. One of the two inputs is required, and base64 must be valid (400 invalid_request); an unknown key answers 404 key_not_found. Open to any member of the tenant. Writes the audit event encryption.encrypt (size only).

Route: /v1/encryption/encrypt (POST).

NameTypeDefaultRequiredDescription
ctxcontext.ContextyesContext of the call: cancellation and deadline.
bodyanyyesKey, data to encrypt and associated data.
opts...CallOptionnoPer call options (query, idempotency key, traceparent, headers).

Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Encrypt data with a tenant key". The error is a typed error of the SDK, nil on success.

Raises: error, the typed errors of the transport (Errors).

PrivacyService.Mask​

Mask(ctx context.Context, text string, opts ...CallOption) (json.RawMessage, error)

Redact sensitive data from a text. Same as inspect, in mode mask by default: each finding is replaced by [TYPE] (for example [EMAIL]), or tokenized or blocked when a tenant rule or mode says so; a blocked text comes back empty with blocked: true. Open to any member of the tenant. Writes the audit event dlp.redact.

Route: /v1/dlp/redact (POST).

NameTypeDefaultRequiredDescription
ctxcontext.ContextyesContext of the call: cancellation and deadline.
textstringyesText to inspect or redact.
opts...CallOptionnoPer call options (query, idempotency key, traceparent, headers).

Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Redact sensitive data from a text". The error is a typed error of the SDK, nil on success.

Raises: error, the typed errors of the transport (Errors).

PrivacyService.Tokenize​

Tokenize(ctx context.Context, body any, opts ...CallOption) (json.RawMessage, error)

Tokenize values. Replaces sensitive values by deterministic tokens tok_<type>_<hex> of the tenant (the same value always gives the same token), the values being stored encrypted in the vault. With values, returns tokens; with text, detects the entities and returns the tokenized text, findings and classification. One of the two is required (400 invalid_request). Open to any member of the tenant. Writes the audit event tokenization.tokenize (count only).

Route: /v1/tokenization/tokenize (POST).

NameTypeDefaultRequiredDescription
ctxcontext.ContextyesContext of the call: cancellation and deadline.
bodyanyyesValues or text to tokenize.
opts...CallOptionnoPer call options (query, idempotency key, traceparent, headers).

Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Tokenize values". The error is a typed error of the SDK, nil on success.

Raises: error, the typed errors of the transport (Errors).

Class ApprovalsService​

Approvals. Human in the loop: approval requests for sensitive actions, with separation of duties, quorum and expiry. Agent runs that reach a tool needing approval, promotions of models, agents, tools, skills, MCP servers or plugins, break glass grants and mandates all create approval requests here.

ApprovalsService.Check​

Check(ctx context.Context, id string, opts ...CallOption) (json.RawMessage, error)

Get an approval request. Returns one approval request with its decisions (approver, decision, comment, date) and approvals_count. A pending request past its expiry is marked expired and its waiting run is failed. Open to any member of the tenant. Answers 404 approval_not_found.

Route: /v1/approvals/{approval_id} (GET).

NameTypeDefaultRequiredDescription
ctxcontext.ContextyesContext of the call: cancellation and deadline.
idstringyesIdentifier (UUID) of the approval request.
opts...CallOptionnoPer call options (query, idempotency key, traceparent, headers).

Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Get an approval request". The error is a typed error of the SDK, nil on success.

Raises: error, the typed errors of the transport (Errors).

Class AuditService​

Evidence. Evidence layer of the audit trail: signed seals, offline verifiable bundles, the integrity monitor, the Audit Gateway, encrypted payloads, audited access, legal holds and purge evidence, and the execution configuration of agent runs.

AuditService.VerifyEvidence​

VerifyEvidence(ctx context.Context, opts ...CallOption) (json.RawMessage, error)

Verify the chain and every seal. Verifies the whole tenant chain and every seal and returns tenant_id, valid, chain (hash chain result), seals (count and failures), clock (timestamp failures) and events (number checked). Needs auditor, security_officer or tenant_admin. The verification is recorded in the access log.

Route: /v1/evidence/verify (GET).

NameTypeDefaultRequiredDescription
ctxcontext.ContextyesContext of the call: cancellation and deadline.
opts...CallOptionnoPer call options (query, idempotency key, traceparent, headers).

Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Verify the chain and every seal". The error is a typed error of the SDK, nil on success.

Raises: error, the typed errors of the transport (Errors).

Class TelemetryService​

Telemetry. Traces, request journal, live stream and service level objectives (SLO) of the platform.

TelemetryService.EndSpan​

EndSpan(ctx context.Context, sp *Span, status string, opts ...CallOption) (json.RawMessage, error)

Ingest telemetry spans. Accepts up to 5000 spans and answers 202 with the number accepted, the number stored (a span already known for the same trace and span id is skipped) and the result of each exporter (ok or error). Requires a tenant principal with tenant_admin, developer or agent (403 forbidden).

Route: /v1/telemetry/spans (POST).

NameTypeDefaultRequiredDescription
ctxcontext.ContextyesContext of the call: cancellation and deadline.
sp*SpanyesSpan opened with StartSpan; a span can be ended only once.
statusstringyesFinal status of the span, ok or error.
opts...CallOptionnoPer call options (query, idempotency key, traceparent, headers).

Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Ingest telemetry spans". The error is a typed error of the SDK, nil on success.

Raises: error, the typed errors of the transport (Errors).

TelemetryService.Logs​

Logs(ctx context.Context, opts ...CallOption) (json.RawMessage, error)

List the request journal. Request journal of the tenant from the span summaries, newest first: one line per span with its time, level (error when the span failed, else info), service, name, message (error type, or method, route and status code), duration, trace, span, run and kept attributes. Never a prompt or a model output. Requires a tenant principal with platform_admin, tenant_admin, auditor, viewer or support_engineer (403 forbidden). An unknown level or a from after to answers 400 invalid_request.

Route: /v1/telemetry/logs (GET).

NameTypeDefaultRequiredDescription
ctxcontext.ContextyesContext of the call: cancellation and deadline.
opts...CallOptionnoPer call options (query, idempotency key, traceparent, headers).

Returns: (json.RawMessage, error). Decoded JSON answer of the operation "List the request journal". The error is a typed error of the SDK, nil on success.

Raises: error, the typed errors of the transport (Errors).

TelemetryService.StartSpan​

StartSpan(name string, traceID string, parentSpanID string, attributes map[string]any) *Span

StartSpan opens a span (new trace when traceID is empty).

NameTypeDefaultRequiredDescription
namestringyesName of the span.
traceIDstringyesTrace to join; empty starts a new trace with a random identifier.
parentSpanIDstringyesIdentifier of the parent span, empty for a root span.
attributesmap[string]anyyesInitial attributes of the span; nil gives an empty map.

Returns: *Span. A Span: Span is a client side span; EndSpan sends it to POST /v1/telemetry/spans.

TelemetryService.Stream​

Stream(ctx context.Context, opts ...CallOption) (*SSEStream, error)

Stream live telemetry events. Server-Sent Events (text/event-stream) of the tenant: a metrics event at every tick (requests, errors, error rate and p95 latency over the last minute), a trace event for every new root span and an incident event for every incident created or changed. Each event carries an id: (a timestamp) the client sends back as Last-Event-ID or since to resume. The stream closes after timeout seconds (the EventSource reconnects after 3 seconds) or after max_events events. Requires a tenant principal with platform_admin, tenant_admin, auditor, viewer or support_engineer.

Route: /v1/telemetry/stream (GET).

NameTypeDefaultRequiredDescription
ctxcontext.ContextyesContext of the call: cancellation and deadline.
opts...CallOptionnoPer call options (query, idempotency key, traceparent, headers).

Returns: (*SSEStream, error). A SSEStream: SSEStream reads Server-Sent Events; "data: [DONE]" ends the stream. Always Close it. The error is a typed error of the SDK, nil on success.

Raises: error, the typed errors of the transport (Errors).

TelemetryService.Traces​

Traces(ctx context.Context, opts ...CallOption) (json.RawMessage, error)

List the recent traces. Recent traces of the tenant, newest first: one row per root span with its name, service, start, duration, status, run, session and its span and error counts. Requires a tenant principal with platform_admin, tenant_admin, auditor, viewer or support_engineer (403 forbidden). An unknown status or a from after to answers 400 invalid_request.

Route: /v1/telemetry/traces (GET).

NameTypeDefaultRequiredDescription
ctxcontext.ContextyesContext of the call: cancellation and deadline.
opts...CallOptionnoPer call options (query, idempotency key, traceparent, headers).

Returns: (json.RawMessage, error). Decoded JSON answer of the operation "List the recent traces". The error is a typed error of the SDK, nil on success.

Raises: error, the typed errors of the transport (Errors).

Class SecurityService​

SecurityService groups the endpoints of: platform security posture and tenant security settings.

SecurityService.CancelRun​

CancelRun(ctx context.Context, runID string, opts ...CallOption) (json.RawMessage, error)

Cancel a run. Moves the run to cancelled with the error cancelled; its active sub-agent runs are cancelled too. Needs tenant_admin, developer, agent or security_officer. A run already terminal answers 409 invalid_transition. Audited as run.transition.

Route: /v1/runs/{run_id}/cancel (POST).

NameTypeDefaultRequiredDescription
ctxcontext.ContextyesContext of the call: cancellation and deadline.
runIDstringyesIdentifier (UUID) of the run.
opts...CallOptionnoPer call options (query, idempotency key, traceparent, headers).

Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Cancel a run". The error is a typed error of the SDK, nil on success.

Raises: error, the typed errors of the transport (Errors).

SecurityService.CheckState​

CheckState(ctx context.Context, opts ...CallOption) (json.RawMessage, error)

Get the security posture. Returns environment, generated_at, protections (authentication methods and other protections in force), checks (each with its status pass, warn or fail, severity and message) and summary (number of checks per status). For a caller with a tenant, also tenant with the security settings of the tenant, which some checks take into account. Needs security_officer or tenant_admin. Read only.

Route: /v1/security/posture (GET).

NameTypeDefaultRequiredDescription
ctxcontext.ContextyesContext of the call: cancellation and deadline.
opts...CallOptionnoPer call options (query, idempotency key, traceparent, headers).

Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Get the security posture". The error is a typed error of the SDK, nil on success.

Raises: error, the typed errors of the transport (Errors).

SecurityService.ReportIncident​

ReportIncident(ctx context.Context, body any, opts ...CallOption) (json.RawMessage, error)

Open an incident. Opens an incident in status open, adds the created entry to the timeline and forwards it to the SIEM. Needs tenant_admin, security_officer, developer or agent. An unknown severity answers 400 invalid_request. Writes the audit event incident.create. The answer (201) carries the incident with its timeline.

Route: /v1/incidents (POST).

NameTypeDefaultRequiredDescription
ctxcontext.ContextyesContext of the call: cancellation and deadline.
bodyanyyesTitle, severity, description, category, resources and assignee.
opts...CallOptionnoPer call options (query, idempotency key, traceparent, headers).

Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Open an incident". The error is a typed error of the SDK, nil on success.

Raises: error, the typed errors of the transport (Errors).