Provisioning API

To let Gravity provision accounts on your platform automatically, you expose one endpoint: Gravity sends you a user’s email, you create an account under that email and return the credentials. That’s the whole required contract. You set your API base URL and mint the shared signing secret in the Index dashboard; no Gravity-side code changes are needed.

The create endpoint (required)

Gravity calls:

POST {your-base-url}/accounts
Content-Type: application/json
X-Gravity-Timestamp: <unix seconds>
X-Gravity-Signature: v1=<hex hmac>

{ "email": "user@example.com", "ttl_seconds": 604800 }

You create the account/resource under that email and respond:

{
  "account_ref": "<your account or resource id>",
  "credentials": { "PAT": "..." }
}

credentials is a flat object of env-var-style keys: whatever a coding agent should write into a project’s environment (DATABASE_URL, an API key, a PAT). Gravity delivers them to the agent exactly once, then holds them only encrypted at rest. Send your own welcome email to the user at creation time. The account is theirs, on your platform, from the moment it’s created.

Optional endpoints

Account lookup (recommended)

POST {base}/accounts/lookup with { "email": "..." }, returning { "exists": true }. When you expose this, Gravity checks it before creating anything and the agent tells the user “you already have an account” instead of creating a duplicate. Lookup failures never block provisioning.

Cleanup

DELETE {base}/accounts/{account_ref}. Called best-effort if Gravity fails to persist a provision after you created the resource, so nothing is stranded.

Ownership handoff (only if you need it)

Only relevant if your platform creates the resource somewhere the user can’t immediately log into (e.g. a partner org) and needs the user to click a link to move it into their own account. In that case also return ownership_url (an https URL on your site) and optionally expires_at from the create call; Gravity passes it through to the agent verbatim. When the user completes the handoff, you can notify Gravity with a signed webhook:

POST https://index.trygravity.ai/provision/webhook/{your-service-slug}

{ "event": "ownership.confirmed", "provision_id": "<uuid Gravity sent>" }

If you create the account directly under the user’s email (most platforms), skip all of this.

Request signing

Every request Gravity sends you is signed with the shared secret you minted in the dashboard. Verify it before creating anything:

payload   = "{timestamp}.{METHOD}.{path}.{raw_body}"
signature = "v1=" + hex(hmac_sha256(secret, payload))

METHOD: uppercase HTTP method
path: request path only, no host/query
raw_body: exact request body bytes (empty string for bodyless requests)
Reject timestamp skew over 300 seconds (replay protection)
Compare with a constant-time comparison

Reference implementation:

import hmac, hashlib, time

def sign(secret: str, method: str, path: str, body: bytes) -> dict:
    ts = str(int(time.time()))
    payload = ".".join([ts, method.upper(), path]).encode() + b"." + body
    sig = "v1=" + hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return {"X-Gravity-Timestamp": ts, "X-Gravity-Signature": sig}

Webhooks you send to Gravity are signed the same way, with the same secret.

What the agent receives

Gravity turns your create response into a single response to the requesting agent; you never talk to the agent directly:

{
  "provision_id": "0b1e…",
  "service_slug": "your-service",
  "status": "provisioned",
  "credentials": { "PAT": "..." },
  "credentials_delivery": "inline_once",
  "env_vars": ["YOUR_SERVICE_PAT"],
  "integration_steps": ["Set YOUR_SERVICE_PAT in your env", "..."]
}

The agent writes the credentials into the project environment and keeps building.

Attribution & billing

Every provision mints a grclid and emits a conversion event at provision time, the moment the account is created and credentials are delivered. Same ledger and CPA billing as click-through conversions.

Checklist

Implement POST {base}/accounts

Verify the signature, create the account under the email, return credentials.

Configure the dashboard

Turn on API provisioning for your service, save the base URL, mint the signing secret.

Send your own welcome email on creation

Recommended. Your brand, your inbox placement.

Questions? Contact us at myles@trygravity.ai.

Start here

Provisioning

Explore

Interfaces

Partners

Provisioning API

The create endpoint (required)

Optional endpoints

Request signing

What the agent receives

Attribution & billing

Checklist

​The create endpoint (required)

​Optional endpoints

​Request signing

​What the agent receives

​Attribution & billing

​Checklist

The create endpoint (required)

Optional endpoints

Request signing

What the agent receives

Attribution & billing

Checklist