Skip to content
EdgeKit

List the signed-in user’s grants

GET
/v1/grants
curl --request GET \
  --url https://your-tenant-host/v1/grants \
  --header 'x-edgekit-site-id: site_example' \
  --cookie ek.session_token=<ek.session_token>

Every grant this person holds that reaches the selected site, newest term first: their own and their organizations’, pinned to the site or covered by the product. Expired, suspended and revoked grants are included and labelled: a purchase that has lapsed is part of the answer to what have I bought. Carries no money; a grant has no price by construction.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
x-edgekit-site-id
required

The site this request is for, within this tenant. Every official EdgeKit SDK sets it from the client you configured; set it yourself only when calling this API directly.

string
>= 1 characters <= 128 characters

Example 

site_example

The site this request is for, within this tenant. Every official EdgeKit SDK sets it from the client you configured; set it yourself only when calling this API directly.

Responses

Section titled “Responses”

200

Section titled “200”

The user’s grants on this site.

Media typeapplication/json
object
grants
required

Every grant the signed-in user holds that reaches the selected site — their own and their organizations’, pinned to the site or covered by the product. Newest term first. Not paged: a person’s commercial history with one organization is bounded by what they have bought.

Array<object>
object
id
required
string format: uuid
state
required

What a screen shows: status and the expiry date folded into one value. revoked and suspended beat the clock, so a revoked grant whose term also lapsed reports revoked. Open: render an unknown member by status.

string
status
required

The stored status: active | suspended | revoked. Sent beside state because a suspended term still exists: dunning and a billing-provider pause both suspend, and neither is an expiry.

string
source
required

Who minted it: recurly, comp, import, api. The organization’s own vocabulary rather than an enum, so an importer’s own value arrives verbatim.

string
reason
required

Why it was minted: purchase, gift, promo, partner, school, staff, winback. Null on older grants, written before source was split into who and why.

string | null
startsAt
required

UTC ISO. Typed nullable, but always set in practice.

string | null format: date-time
expiresAt
required

UTC ISO, or null for open-ended. Null is a lifetime grant, never a missing value.

string | null format: date-time
trialEndsAt
required

UTC ISO. Access before this instant was granted without payment — set for comped and imported trials too, which no billing provider’s own trial dates can see.

string | null format: date-time
product
required

The access set this grant references: what it covers. Carries no price — that is the offer’s, and the money is the billing provider’s invoice.

object
id
required
string format: uuid
slug
required
string
name
required
string
offer
required

The merchandised offer it was bought as, or null for a grant that predates the offer describing it — an import, or a comp nobody sold.

object
id
required
string format: uuid
code
required
string
name
required
string
organization
required

Set only when this person reaches the grant through a seat in one of their organizations. Omitting it on a screen shows somebody their employer’s grant as if they had bought it.

object
id
required
string format: uuid
name
required
string

Example 

{
  "grants": [
    {
      "id": "01999b1e-6f3a-7c2d-9e51-2a4c8d0f6b31",
      "state": "live",
      "status": "active",
      "source": "recurly",
      "reason": "purchase",
      "startsAt": "2026-08-16T09:12:44.000Z",
      "product": {
        "id": "01999b1e-6f3a-7c2d-9e51-2a4c8d0f6b31"
      },
      "offer": {
        "id": "01999b1e-6f3a-7c2d-9e51-2a4c8d0f6b31"
      },
      "organization": {
        "id": "01999b1e-6f3a-7c2d-9e51-2a4c8d0f6b31"
      }
    }
  ]
}

400

Section titled “400”

Invalid request.

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
details

Example 

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key."
  }
}

401

Section titled “401”

Missing or invalid credential.

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
details

Example 

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key."
  }
}

403

Section titled “403”

Not allowed.

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
details

Example 

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key."
  }
}

404

Section titled “404”

Resource not found.

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
details

Example 

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key."
  }
}

422

Section titled “422”

Request validation failed.

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
details

Example 

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key."
  }
}

500

Section titled “500”

Unexpected error.

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
details

Example 

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key."
  }
}