API Keys

We use API keys to authenticate requests. You can create and manage seller and organization API keys in the vivenu Dashboard under Settings > Developers > API Keys, or through the endpoints on this page.

Send the secret in an Authorization header with a Bearer prefix. Unauthenticated private requests fail with 401 Unauthorized. The plaintext secret is returned only when the key is created. Later list, get, and update responses omit key.

Treat API keys as credentials for server-side communication only. Do not expose them in browser or mobile clients.

A seller account can have at most 100 API keys. There is no delete endpoint; set active to false or let expiresAt pass. Expired or inactive keys cannot authenticate.

Seller keys and organization keys

Seller keys have a sellerId and authenticate seller-scoped API endpoints.

Organization keys have an orgId and authenticate organization-scoped endpoints (labeled ORG in this documentation). Create them by sending orgId on POST /api/keys. Organization keys cannot use fullSellerAccess or permissions.

Access control

Seller keys use fullSellerAccess and permissions:

  • fullSellerAccess: true — seller-admin equivalent access. The stored permissions list is empty and ignored. New API permissions added later are included automatically.
  • fullSellerAccess: false with a permissions array — the key may call only endpoints covered by those permissions. Missing permissions fail with 403 and a message such as Missing permission "events:list".
  • fullSellerAccess: false with an empty or omitted permissions array — the key authenticates, but permission-protected endpoints fail until you assign permissions.

permissions values are resource:action strings such as tickets:list or webhooks:update. Only seller-scoped, API-key-assignable permissions are accepted.

Create, list, and update keys from the dashboard or with a dashboard user session. Use GET /api/keys/info to inspect the key you are authenticated with.

Expiration

expiresAt is an optional ISO timestamp. Omit it, or send null on update, for a key that does not expire automatically. On create, expiresAt must be strictly in the future and at most one year from now. After that instant the key fails authentication immediately.

The API Key Object

Required attributes

  • Name
    _id
    Type
    string
    Description

    The ID of the API key.

  • Name
    name
    Type
    string
    Description

    An internal name to identify the API key.

  • Name
    key
    Type
    string
    Description

    The secret key to be used to authenticate against the API.

  • Name
    createdAt
    Type
    string date-time
    Description

    An ISO Timestamp indicating when the API Key was created.

  • Name
    updatedAt
    Type
    string date-time
    Description

    An ISO Timestamp indicating when the API Key was last updated.

Optional attributes

  • Name
    active
    Type
    boolean
    Description

    Whether the API key can be used to authenticate against the API.

  • Name
    sellerId
    Type
    string
    Description

    The ID of the seller that owns the API key.

  • Name
    orgId
    Type
    string
    Description

    The ID of the organisation that owns the API key.

  • Name
    createdBy
    Type
    object
    Description

    The entity that created the API key.

    Required nested attributes (2)
    • Name
      type
      Type
      enum(USER, APP, API_KEY, SYSTEM)
      Description

      The type of the entity

    • Name
      id
      Type
      string
      Description

      The ID of the entity

  • Name
    expiresAt
    Type
    string date-time
    Description

    Optional ISO instant after which the key no longer authenticates; omit or null for no automatic expiry.

  • Name
    version
    Type
    integer
    Description

    The version of the API key.

  • Name
    fullSellerAccess
    Type
    boolean
    Description

    Seller keys only: when true, grants full seller access (seller-admin equivalent).

  • Name
    permissions
    Type
    array<enum(accessLists:create, accessLists:list, accessLists:update, accessUsers:create, accessUsers:list, accessUsers:update, attributes:create, attributes:update, bundles:create, bundles:list, bundles:update, checkouts:list, couponSeries:create, couponSeries:list, couponSeries:update, coupons:create, coupons:list, coupons:update, customerPaymentMethods:create, customerPaymentMethods:list, customerPaymentMethods:update, customers:create, customers:list, customers:update, dataFields:create, dataFields:update, distributors:list, fundraise:donations:create, fundraise:donations:list, entitlements:create, entitlements:list, entitlements:update, eventSeries:create, eventSeries:list, eventSeries:update, events:create, events:list, events:update, feeSchemes:create, feeSchemes:list, feeSchemes:update, fundraise:campaigns:create, fundraise:campaigns:list, fundraise:campaigns:update, fundraise:funds:create, fundraise:funds:list, fundraise:funds:update, invoices:create, invoices:list, invoices:update, marketing:campaigns:create, marketing:campaigns:list, marketing:campaigns:update, packageConfigs:create, packageConfigs:list, packageConfigs:update, packages:list, paymentGateways:create, paymentGateways:list, paymentGateways:update, paymentPlans:list, paymentPlans:update, paymentStrategies:create, paymentStrategies:list, paymentStrategies:update, perks:create, perks:list, perks:update, fundraise:pledges:create, fundraise:pledges:list, posDevices:create, posDevices:list, posDevices:update, priceTables:create, priceTables:list, priceTables:update, products:create, products:list, products:update, purchaseIntents:create, purchaseIntents:list, purchaseIntentsStrategies:create, purchaseIntentsStrategies:list, purchaseIntentsStrategies:update, purchaseIntents:update, rebookingStrategies:create, rebookingStrategies:list, rebookingStrategies:update, salesChannelGroups:create, salesChannelGroups:list, salesChannels:create, salesChannels:list, scanGroups:create, scanGroups:list, scanGroups:update, scanZones:create, scanZones:list, scanZones:update, scans:create, scans:list, subscriptionCycles:create, subscriptionCycles:list, subscriptionCycles:update, subscriptionPlans:create, subscriptionPlans:list, subscriptionPlans:update, subscriptions:list, subscriptions:update, tickets:create, tickets:list, tickets:update, transactions:create, transactions:list, transactions:update, transfers:list, transfers:update, vouchers:create, vouchers:list, vouchers:update, webhooks:create, webhooks:list, webhooks:update)>
    Description

    Explicit permissions

Example

{
  "_id": "507f191e810c19729de860ea",
  "name": "Some fancy Name",
  "key": "key_somerandomcombinationofnumbersandletters",
  "createdAt": "2030-01-23T23:00:00.123Z",
  "updatedAt": "2030-01-23T23:00:00.123Z",
  "active": true,
  "sellerId": "507f191e810c19729de860ea",
  "orgId": "507f191e810c19729de860ea",
  "createdBy": {
    "type": "USER",
    "id": "507f191e810c19729de860ea"
  },
  "expiresAt": "2030-01-23T23:00:00.123Z",
  "version": 1,
  "fullSellerAccess": true,
  "permissions": [
    "accessLists:create"
  ]
}
POST/api/keys

Create an API Key

Create an API Key

Payload

Required attributes

  • Name
    name
    Type
    string
    Description

    An internal name to identify the API key.

Optional attributes

  • Name
    orgId
    Type
    string
    Description

    The organization ID for which to create the API key.

  • Name
    expiresAt
    Type
    string date-time
    Description

    Optional expiry time (strictly future, at most one year); omit for keys that do not auto-expire.

  • Name
    permissions
    Type
    array<enum(accessLists:create, accessLists:list, accessLists:update, accessUsers:create, accessUsers:list, accessUsers:update, attributes:create, attributes:update, bundles:create, bundles:list, bundles:update, checkouts:list, couponSeries:create, couponSeries:list, couponSeries:update, coupons:create, coupons:list, coupons:update, customerPaymentMethods:create, customerPaymentMethods:list, customerPaymentMethods:update, customers:create, customers:list, customers:update, dataFields:create, dataFields:update, distributors:list, fundraise:donations:create, fundraise:donations:list, entitlements:create, entitlements:list, entitlements:update, eventSeries:create, eventSeries:list, eventSeries:update, events:create, events:list, events:update, feeSchemes:create, feeSchemes:list, feeSchemes:update, fundraise:campaigns:create, fundraise:campaigns:list, fundraise:campaigns:update, fundraise:funds:create, fundraise:funds:list, fundraise:funds:update, invoices:create, invoices:list, invoices:update, marketing:campaigns:create, marketing:campaigns:list, marketing:campaigns:update, packageConfigs:create, packageConfigs:list, packageConfigs:update, packages:list, paymentGateways:create, paymentGateways:list, paymentGateways:update, paymentPlans:list, paymentPlans:update, paymentStrategies:create, paymentStrategies:list, paymentStrategies:update, perks:create, perks:list, perks:update, fundraise:pledges:create, fundraise:pledges:list, posDevices:create, posDevices:list, posDevices:update, priceTables:create, priceTables:list, priceTables:update, products:create, products:list, products:update, purchaseIntents:create, purchaseIntents:list, purchaseIntentsStrategies:create, purchaseIntentsStrategies:list, purchaseIntentsStrategies:update, purchaseIntents:update, rebookingStrategies:create, rebookingStrategies:list, rebookingStrategies:update, salesChannelGroups:create, salesChannelGroups:list, salesChannels:create, salesChannels:list, scanGroups:create, scanGroups:list, scanGroups:update, scanZones:create, scanZones:list, scanZones:update, scans:create, scans:list, subscriptionCycles:create, subscriptionCycles:list, subscriptionCycles:update, subscriptionPlans:create, subscriptionPlans:list, subscriptionPlans:update, subscriptions:list, subscriptions:update, tickets:create, tickets:list, tickets:update, transactions:create, transactions:list, transactions:update, transfers:list, transfers:update, vouchers:create, vouchers:list, vouchers:update, webhooks:create, webhooks:list, webhooks:update)>
    Description

    Seller API keys only: initial permissions.

  • Name
    fullSellerAccess
    Type
    boolean
    Description

    Seller API keys only: when true, grants full seller access.

Request

POST
/api/keys
const response = await fetch('https://vivenu.com/api/keys', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer {token}',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(  {
    "name": "Some fancy Name",
    "orgId": "507f191e810c19729de860ea",
    "expiresAt": "2030-01-23T23:00:00.123Z",
    "permissions": [
      "accessLists:create"
    ],
    "fullSellerAccess": true
  }),
})

const data = await response.json()

Response (201)

{
  "_id": "507f191e810c19729de860ea",
  "name": "Some fancy Name",
  "key": "key_somerandomcombinationofnumbersandletters",
  "createdAt": "2030-01-23T23:00:00.123Z",
  "updatedAt": "2030-01-23T23:00:00.123Z",
  "active": true,
  "sellerId": "507f191e810c19729de860ea",
  "orgId": "507f191e810c19729de860ea",
  "createdBy": {
    "type": "USER",
    "id": "507f191e810c19729de860ea"
  },
  "expiresAt": "2030-01-23T23:00:00.123Z",
  "version": 1,
  "fullSellerAccess": true,
  "permissions": [
    "accessLists:create"
  ]
}
GET/api/keys

Get All API Keys

Get All API Keys

Request

GET
/api/keys
const response = await fetch('https://vivenu.com/api/keys', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer {token}',
  },
})

const data = await response.json()

Response (200)

[
  {
    "_id": "507f191e810c19729de860ea",
    "name": "Some fancy Name",
    "createdAt": "2030-01-23T23:00:00.123Z",
    "updatedAt": "2030-01-23T23:00:00.123Z",
    "active": true,
    "sellerId": "507f191e810c19729de860ea",
    "orgId": "507f191e810c19729de860ea",
    "createdBy": {
      "type": "USER",
      "id": "507f191e810c19729de860ea"
    },
    "expiresAt": "2030-01-23T23:00:00.123Z",
    "version": 1,
    "fullSellerAccess": true,
    "permissions": [
      "accessLists:create"
    ]
  }
]
GET/api/keys/:id

Get an API Key

Get an API Key

Request

GET
/api/keys/:id
const response = await fetch('https://vivenu.com/api/keys/507f191e810c19729de860ea', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer {token}',
  },
})

const data = await response.json()

Response (200)

{
  "_id": "507f191e810c19729de860ea",
  "name": "Some fancy Name",
  "createdAt": "2030-01-23T23:00:00.123Z",
  "updatedAt": "2030-01-23T23:00:00.123Z",
  "active": true,
  "sellerId": "507f191e810c19729de860ea",
  "orgId": "507f191e810c19729de860ea",
  "createdBy": {
    "type": "USER",
    "id": "507f191e810c19729de860ea"
  },
  "expiresAt": "2030-01-23T23:00:00.123Z",
  "version": 1,
  "fullSellerAccess": true,
  "permissions": [
    "accessLists:create"
  ]
}
PUT/api/keys/:id

Update an API Key

Update an API Key

Payload

Optional attributes

  • Name
    active
    Type
    boolean
    Description

    Whether the API key can be used to authenticate against the API.

  • Name
    name
    Type
    string
    Description

    An internal name to identify the API key.

  • Name
    expiresAt
    Type
    oneOf
    Description

    Optional expiry; send null to clear automatic expiry.

    One of — Only one of the following types

    array | boolean | number | object | string

  • Name
    permissions
    Type
    array<enum(accessLists:create, accessLists:list, accessLists:update, accessUsers:create, accessUsers:list, accessUsers:update, attributes:create, attributes:update, bundles:create, bundles:list, bundles:update, checkouts:list, couponSeries:create, couponSeries:list, couponSeries:update, coupons:create, coupons:list, coupons:update, customerPaymentMethods:create, customerPaymentMethods:list, customerPaymentMethods:update, customers:create, customers:list, customers:update, dataFields:create, dataFields:update, distributors:list, fundraise:donations:create, fundraise:donations:list, entitlements:create, entitlements:list, entitlements:update, eventSeries:create, eventSeries:list, eventSeries:update, events:create, events:list, events:update, feeSchemes:create, feeSchemes:list, feeSchemes:update, fundraise:campaigns:create, fundraise:campaigns:list, fundraise:campaigns:update, fundraise:funds:create, fundraise:funds:list, fundraise:funds:update, invoices:create, invoices:list, invoices:update, marketing:campaigns:create, marketing:campaigns:list, marketing:campaigns:update, packageConfigs:create, packageConfigs:list, packageConfigs:update, packages:list, paymentGateways:create, paymentGateways:list, paymentGateways:update, paymentPlans:list, paymentPlans:update, paymentStrategies:create, paymentStrategies:list, paymentStrategies:update, perks:create, perks:list, perks:update, fundraise:pledges:create, fundraise:pledges:list, posDevices:create, posDevices:list, posDevices:update, priceTables:create, priceTables:list, priceTables:update, products:create, products:list, products:update, purchaseIntents:create, purchaseIntents:list, purchaseIntentsStrategies:create, purchaseIntentsStrategies:list, purchaseIntentsStrategies:update, purchaseIntents:update, rebookingStrategies:create, rebookingStrategies:list, rebookingStrategies:update, salesChannelGroups:create, salesChannelGroups:list, salesChannels:create, salesChannels:list, scanGroups:create, scanGroups:list, scanGroups:update, scanZones:create, scanZones:list, scanZones:update, scans:create, scans:list, subscriptionCycles:create, subscriptionCycles:list, subscriptionCycles:update, subscriptionPlans:create, subscriptionPlans:list, subscriptionPlans:update, subscriptions:list, subscriptions:update, tickets:create, tickets:list, tickets:update, transactions:create, transactions:list, transactions:update, transfers:list, transfers:update, vouchers:create, vouchers:list, vouchers:update, webhooks:create, webhooks:list, webhooks:update)>
    Description

    When sent on a seller API key: full replacement permissions list.

  • Name
    fullSellerAccess
    Type
    boolean
    Description

    Seller API keys only: when true, grants full seller access.

Request

PUT
/api/keys/:id
const response = await fetch('https://vivenu.com/api/keys/507f191e810c19729de860ea', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer {token}',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(  {
    "active": true,
    "name": "Some fancy Name",
    "expiresAt": [],
    "permissions": [
      "accessLists:create"
    ],
    "fullSellerAccess": true
  }),
})

const data = await response.json()

Response (200)

{
  "_id": "507f191e810c19729de860ea",
  "name": "Some fancy Name",
  "createdAt": "2030-01-23T23:00:00.123Z",
  "updatedAt": "2030-01-23T23:00:00.123Z",
  "active": true,
  "sellerId": "507f191e810c19729de860ea",
  "orgId": "507f191e810c19729de860ea",
  "createdBy": {
    "type": "USER",
    "id": "507f191e810c19729de860ea"
  },
  "expiresAt": "2030-01-23T23:00:00.123Z",
  "version": 1,
  "fullSellerAccess": true,
  "permissions": [
    "accessLists:create"
  ]
}
GET/api/keys/info

Get Information about the used API Key

Get Information about the used API Key

Request

GET
/api/keys/info
const response = await fetch('https://vivenu.com/api/keys/info', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer {token}',
  },
})

const data = await response.json()

Response (200)

{
  "_id": "507f191e810c19729de860ea",
  "name": "Some fancy Name",
  "createdAt": "2030-01-23T23:00:00.123Z",
  "updatedAt": "2030-01-23T23:00:00.123Z",
  "active": true,
  "sellerId": "507f191e810c19729de860ea",
  "orgId": "507f191e810c19729de860ea",
  "createdBy": {
    "type": "USER",
    "id": "507f191e810c19729de860ea"
  },
  "expiresAt": "2030-01-23T23:00:00.123Z",
  "version": 1,
  "fullSellerAccess": true,
  "permissions": [
    "accessLists:create"
  ]
}
POST/api/keys/default

Get or Create a Default API Key

Get or Create a Default API Key

Payload

Required attributes

  • Name
    sellerId
    Type
    string
    Description

    The seller ID to get or create the API key for.

Request

POST
/api/keys/default
const response = await fetch('https://vivenu.com/api/keys/default', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer {token}',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(  {
    "sellerId": "507f191e810c19729de860ea"
  }),
})

const data = await response.json()

Response (200)

{
  "_id": "507f191e810c19729de860ea",
  "name": "Some fancy Name",
  "key": "key_somerandomcombinationofnumbersandletters",
  "createdAt": "2030-01-23T23:00:00.123Z",
  "updatedAt": "2030-01-23T23:00:00.123Z",
  "active": true,
  "sellerId": "507f191e810c19729de860ea",
  "orgId": "507f191e810c19729de860ea",
  "createdBy": {
    "type": "USER",
    "id": "507f191e810c19729de860ea"
  },
  "expiresAt": "2030-01-23T23:00:00.123Z",
  "version": 1,
  "fullSellerAccess": true,
  "permissions": [
    "accessLists:create"
  ]
}

Was this page helpful?