Class: AgentAdmit::TokensClient

Inherits:
Object
  • Object
show all
Defined in:
lib/agentadmit/tokens_client.rb

Overview

TokensClient — issue, exchange, and revoke connection tokens via the AgentAdmit hosted service.

Constant Summary collapse

UNSET =

Sentinel for issue_token’s duration_seconds: leave the field out of the request entirely, so AgentAdmit applies its default (30 days). Pass nil instead for an until-revoked connection (explicit JSON null).

Object.new.freeze

Instance Method Summary collapse

Constructor Details

#initialize(config = nil) ⇒ TokensClient

Returns a new instance of TokensClient.



18
19
20
21
 
# File 'lib/agentadmit/tokens_client.rb', line 18

def initialize(config = nil)
  @config = config || AgentAdmit.configuration || Config.new
  @config.validate_api_key!
end

Instance Method Details

#exchange(connection_token, agent_label: nil, agent_id: nil) ⇒ Hash

Exchange a single-use connection token for an access token. Calls POST /api/v1/exchange — unauthenticated by design: the connection token itself is the credential, so the operator API key is NOT sent.

Parameters:

  • connection_token (String) —

    the ag_ct_… connection token

  • agent_label (String, nil) (defaults to: nil) —

    human-readable agent name

  • agent_id (String, nil) (defaults to: nil) —

    agent identifier

Returns:

  • (Hash) —

    the exchange response — “access_token” is the ag_at_… token

Raises:



62
63
64
65
66
67
68
 
# File 'lib/agentadmit/tokens_client.rb', line 62

def exchange(connection_token, agent_label: nil, agent_id: nil)
  body = { "token" => connection_token }
  body["agent_label"] = agent_label if agent_label
  body["agent_id"] = agent_id if agent_id

  post("/api/v1/exchange", body, authenticated: false, op: "exchange")
end

#issue_token(user_id:, scopes:, role: nil, duration_seconds: UNSET) ⇒ Hash

Issue a connection token for one of your users. Calls POST /api/v1/apps/app_id/token.

The duration is tri-state:

  • omit the argument — field omitted; AgentAdmit applies its default (30 days)

  • nil — explicit JSON null; the connection lasts until revoked

  • Integer — explicit duration in seconds (60–31536000)

Parameters:

  • user_id (String) —

    your app’s identifier for the user

  • scopes (Array<String>) —

    scopes the connection grants

  • role (String, nil) (defaults to: nil) —

    the user’s role on the connection

  • duration_seconds (Integer, nil, UNSET) (defaults to: UNSET) —

    see above

Returns:

  • (Hash) —

    the issue response — “token” is the self-describing ag_ct_… connection token to hand to the user’s agent

Raises:



41
42
43
44
45
46
47
48
49
 
# File 'lib/agentadmit/tokens_client.rb', line 41

def issue_token(user_id:, scopes:, role: nil, duration_seconds: UNSET)
  body = { "user_id" => user_id, "scopes" => scopes }
  body["role"] = role if role
  # Tri-state: the UNSET sentinel omits the key entirely; nil survives
  # JSON.generate as explicit JSON null (no compact, no nil-guard).
  body["duration_seconds"] = duration_seconds unless duration_seconds.equal?(UNSET)

  post("/api/v1/apps/#{@config.app_id}/token", body, authenticated: true, op: "issue_token")
end

#revoke(connection_id, reason: nil) ⇒ Hash

Revoke a connection (and its access tokens). Calls POST /api/v1/revoke.

Parameters:

  • connection_id (String) —

    the connection to revoke

  • reason (String, nil) (defaults to: nil) —

    optional human-readable reason

Returns:

  • (Hash) —

    the revoke response — { “ok” => true, … }

Raises:



79
80
81
82
83
84
 
# File 'lib/agentadmit/tokens_client.rb', line 79

def revoke(connection_id, reason: nil)
  body = { "connection_id" => connection_id }
  body["reason"] = reason if reason

  post("/api/v1/revoke", body, authenticated: true, op: "revoke")
end