Skip to main content

​
Lifecycle states

registered → active → expired
                ↓
             revoked
StateDescription
activeToken is valid and will pass verification
expiredToken’s exp timestamp has passed — returns TOKEN_EXPIRED
revokedExplicitly revoked via POST /v1/agents/:id/revoke — returns TOKEN_REVOKED

​
Expiry

Default token expiry is 24 hours from issuance. Configurable at registration: 
curl -X POST https://api.imarobot.ai/v1/agents/register \
  -H "Authorization: Bearer sk_test_..." \
  -d '{
    "name": "LongLivedAgent",
    "issuer_domain": "yourdomain.com",
    "scopes": ["read:data"],
    "expiry_seconds": 2592000
  }'
PlanMax expiry
Free24 hours
Developer90 days
Growth90 days
Enterprise1 year

​
Revocation

Revocation is immediate. Once revoked, the next verification call returns TOKEN_REVOKED — no delay, no cache. 
curl -X POST https://api.imarobot.ai/v1/agents/agt_abc123/revoke \
  -H "Authorization: Bearer sk_test_..." \
  -d '{ "reason": "Credential rotation" }'
Revocation is permanent. A revoked agent cannot be un-revoked — register a new agent instead.

​
Offline validation

In offline mode, revocation is not checked. The token is validated cryptographically against the cached public key. A revoked agent may still pass offline validation until the cache refreshes. Use online mode for high-risk actions. Use offline mode for high-volume, low-risk actions where sub-millisecond latency matters.

​
Token rotation

To rotate an agent’s credentials:
  1. Register a new agent — get a new agent_id and token
  2. Update your agent process to use the new token
  3. Revoke the old agent
The Agent SDK’s rotateAgent() method does all three steps in one call.