---
name: Vaultless
description: Ephemeral credential broker to request short-lived, single-use access tokens for external resources.
---

**Base URL:** https://vaultless.onrender.com

# Vaultless Agent Skill

This skill allows you to request scoped, short-lived credentials instead of using hardcoded API keys. 

## Endpoints

### 1. Request a Credential (Mint)

**Endpoint:** `POST /v1/credentials`

Use this to get a token before calling an external resource.

```bash
curl -X POST https://vaultless.onrender.com/v1/credentials \
  -H "Content-Type: application/json" \
  -H "x-agent-id: your-agent-id" \
  -d '{
    "resource": "stripe",
    "action": "refund",
    "constraints": { "max_amount_usd": 50 },
    "ttl_seconds": 300
  }'
```

**Response:**
```json
{
  "grant_id": "uuid",
  "token": "v4.public....",
  "expires_at": "2026-07-09T..."
}
```

### 2. Validate a Credential (For downstream resources)

**Endpoint:** `POST /v1/validate`

Downstream resources call this to verify and atomically consume a token.

```bash
curl -X POST https://vaultless.onrender.com/v1/validate \
  -H "Content-Type: application/json" \
  -d '{
    "token": "v4.public....",
    "resource": "stripe",
    "action": "refund"
  }'
```

**Response (Success - 200 OK):**
```json
{
  "valid": true,
  "grant_id": "uuid",
  "resource": "stripe",
  "action": "refund",
  "constraints": { "max_amount_usd": 50 }
}
```

**Response (Failure - 401/403/409):**
```json
{
  "error": "Token has expired" 
}
```
*(Other errors include: "Token already consumed", "Token has been revoked", "Token scope mismatch", "Invalid or expired token")*

### 3. Revoke a Credential

**Endpoint:** `POST /v1/revoke`

If you don't end up using a token, revoke it explicitly.

```bash
curl -X POST https://vaultless.onrender.com/v1/revoke \
  -H "Content-Type: application/json" \
  -d '{
    "grant_id": "uuid"
  }'
```

**Response (Success - 200 OK):**
```json
{
  "success": true,
  "grant_id": "uuid"
}
```

### 4. Audit Log

**Endpoint:** `GET /v1/audit/:grant_id`

View the lifecycle of a credential.

```bash
curl https://vaultless.onrender.com/v1/audit/GRANT_ID_HERE
```

**Response (Success - 200 OK):**
```json
{
  "grant_id": "uuid",
  "events": [
    {
      "id": "1",
      "event_type": "issued",
      "occurred_at": "2026-07-11T16:06:25.744Z",
      "metadata": null
    },
    {
      "id": "2",
      "event_type": "consumed",
      "occurred_at": "2026-07-11T16:06:26.739Z",
      "metadata": null
    }
  ]
}
```

### 5. Metrics

**Endpoint:** `GET /metrics`

Prometheus-format metrics showing issuance, validation, and lock-contention counts.

```bash
curl https://vaultless.onrender.com/metrics
```

**Response (Success - 200 OK, text/plain):**
```
# HELP vaultless_issuance_total Total tokens minted
# TYPE vaultless_issuance_total counter
vaultless_issuance_total 2
# HELP vaultless_validation_success_total Total successful validations
# TYPE vaultless_validation_success_total counter
vaultless_validation_success_total 1
# HELP vaultless_validation_failure_total Total failed validations
# TYPE vaultless_validation_failure_total counter
vaultless_validation_failure_total 0
# HELP vaultless_lock_contention_total Total concurrent reuse attempts blocked
# TYPE vaultless_lock_contention_total counter
vaultless_lock_contention_total 0
```

## How to use this skill

1. Before calling an external resource on behalf of a task, request a scoped credential from `POST /v1/credentials`, specifying exactly the resource, action, and constraints needed.
2. Present the returned `token` when calling the downstream resource; that resource verifies it via `POST /v1/validate`.
3. If the token ends up unused, call `POST /v1/revoke` with its `grant_id` so it can't be used later.
4. To inspect what happened to a credential, call `GET /v1/audit/:grant_id`.
5. To check overall service health and usage volume, call `GET /metrics`.