Access Users

An Access User represents a handheld or installed device like smartphones or turnstiles at your venue that should be allowed to download and scan Tickets for events.

You can grant access to all events and tickets or just a selected subset of them. Each created Access User receives a unique token that can than be used to authenticate against the API.

Please note:

The issued token can only be used to authenticate against selected /accessusers endpoints. They cannot be used against other endpoints of the vivenu API.

The access user object

Required attributes

Name
sellerId
Type
string
Description
The ID of the seller that owns the access user.
Name
name
Type
string
Description
An internal name to identify the access user
Name
token
Type
string
Description
The token to authenticate against the access-control endpoints.
Name
accessAllEvents
Type
boolean
Description
Whether the access user can access all events of his seller
Name
createdAt
Type
string date-time
Description
An ISO Timestamp indicating when the access user was created.
Name
updatedAt
Type
string date-time
Description
An ISO Timestamp indicating when the access user was updated.

Optional attributes

Name
_id
Type
string
Description
Name
active
Type
boolean
Description
Whether the access user is active or not.
Name
events
Type
array<string>
Description
An array of events the access user can access. Only if accessAllEvents=false.
Name
lastRequest
Type
string date-time
Description
An ISO Timestamp indicating when the access user made the last request.
Name
expires
Type
string date-time
Description
An ISO Timestamp indicating when the access user should expire
Name
isIntegration
Type
boolean
Description
Whether an integration belongs to the access user
Name
integration
Type
enum(simplyX, axess, skidata)
Description
The type of integration belongs to this access user
Name
deviceSettings
Type
object
Description
An object of settings which will be used on the device
Optional nested attributes (2)
Name
accessMode
Type
enum(full, restricted)
Description
'restricted' mode limits access-user visibility while keeping assigned access-control capabilities available.
Name
scanGroupId
Type
string
Description
The ID of the scan group to which the access user assigned.
Name
__v
Type
integer
Description

Example

{
  "sellerId": "507f191e810c19729de860ea",
  "name": "Some fancy Name",
  "token": "{TOKEN}",
  "accessAllEvents": true,
  "createdAt": "2030-01-23T23:00:00.123Z",
  "updatedAt": "2030-01-23T23:00:00.123Z",
  "_id": "507f191e810c19729de860ea",
  "active": true,
  "events": [
    "string"
  ],
  "lastRequest": "2030-01-23T23:00:00.123Z",
  "expires": "2030-01-23T23:00:00.123Z",
  "isIntegration": true,
  "integration": "simplyX",
  "deviceSettings": {
    "accessMode": "full",
    "scanGroupId": "507f191e810c19729de860ea"
  },
  "__v": 1
}

POST/api/accessusers

Create an Access User

Payload

Required attributes

Name
name
Type
string
Description
An internal name to identify the access user

Optional attributes

Name
isIntegration
Type
boolean
Description
Whether an integration belongs to the access user

Request

POST

/api/accessusers

const response = await fetch('https://vivenu.com/api/accessusers', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer {token}',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(  {
    "name": "Some fancy Name",
    "isIntegration": true
  }),
})

const data = await response.json()

Response (201)

{
  "sellerId": "507f191e810c19729de860ea",
  "name": "Some fancy Name",
  "token": "{TOKEN}",
  "accessAllEvents": true,
  "createdAt": "2030-01-23T23:00:00.123Z",
  "updatedAt": "2030-01-23T23:00:00.123Z",
  "_id": "507f191e810c19729de860ea",
  "active": true,
  "events": [
    "string"
  ],
  "lastRequest": "2030-01-23T23:00:00.123Z",
  "expires": "2030-01-23T23:00:00.123Z",
  "isIntegration": true,
  "integration": "simplyX",
  "deviceSettings": {
    "accessMode": "full",
    "scanGroupId": "507f191e810c19729de860ea"
  },
  "__v": 1
}

PUT/api/accessusers/:id

Update an Access User

Payload

Required attributes

Name
name
Type
string
Description
An internal name to identify the access user
Name
accessAllEvents
Type
boolean
Description
Whether the access user can access all events of his seller

Optional attributes

Name
events
Type
array<string>
Description
An array of events the access user can access. Only if accessAllEvents=false.
Name
expires
Type
string date-time
Description
An ISO Timestamp indicating when the access user should expire
Name
active
Type
boolean
Description
Whether the access user is active or not.
Name
lastRequest
Type
string date-time
Description
An ISO Timestamp indicating when the access user made the last request.
Name
integration
Type
enum(simplyX, axess, skidata)
Description
The type of integration belongs to this access user
Name
deviceSettings
Type
object
Description
An object of settings which will be used on the device
Optional nested attributes (2)
Name
accessMode
Type
enum(full, restricted)
Description
'restricted' mode limits access-user visibility while keeping assigned access-control capabilities available.
Name
scanGroupId
Type
string
Description
The ID of the scan group to which the access user assigned.

Request

PUT

/api/accessusers/:id

const response = await fetch('https://vivenu.com/api/accessusers/507f191e810c19729de860ea', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer {token}',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(  {
    "name": "Some fancy Name",
    "accessAllEvents": true,
    "events": [
      "string"
    ],
    "expires": "2030-01-23T23:00:00.123Z",
    "active": true,
    "lastRequest": "2030-01-23T23:00:00.123Z",
    "integration": "simplyX",
    "deviceSettings": {
      "accessMode": "full",
      "scanGroupId": "507f191e810c19729de860ea"
    }
  }),
})

const data = await response.json()

Response (200)

{
  "sellerId": "507f191e810c19729de860ea",
  "name": "Some fancy Name",
  "token": "{TOKEN}",
  "accessAllEvents": true,
  "createdAt": "2030-01-23T23:00:00.123Z",
  "updatedAt": "2030-01-23T23:00:00.123Z",
  "_id": "507f191e810c19729de860ea",
  "active": true,
  "events": [
    "string"
  ],
  "lastRequest": "2030-01-23T23:00:00.123Z",
  "expires": "2030-01-23T23:00:00.123Z",
  "isIntegration": true,
  "integration": "simplyX",
  "deviceSettings": {
    "accessMode": "full",
    "scanGroupId": "507f191e810c19729de860ea"
  },
  "__v": 1
}

DELETE/api/accessusers/:id

Delete an Access User

Request

DELETE

/api/accessusers/:id

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

const data = await response.json()

Response (200)

{
  "sellerId": "507f191e810c19729de860ea",
  "name": "Some fancy Name",
  "token": "{TOKEN}",
  "accessAllEvents": true,
  "createdAt": "2030-01-23T23:00:00.123Z",
  "updatedAt": "2030-01-23T23:00:00.123Z",
  "_id": "507f191e810c19729de860ea",
  "active": true,
  "events": [
    "string"
  ],
  "lastRequest": "2030-01-23T23:00:00.123Z",
  "expires": "2030-01-23T23:00:00.123Z",
  "isIntegration": true,
  "integration": "simplyX",
  "deviceSettings": {
    "accessMode": "full",
    "scanGroupId": "507f191e810c19729de860ea"
  },
  "__v": 1
}

GET/api/accessusers

Get all Access Users

Request

GET

/api/accessusers

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

const data = await response.json()

Response (200)

[
  {
    "sellerId": "507f191e810c19729de860ea",
    "name": "Some fancy Name",
    "token": "{TOKEN}",
    "accessAllEvents": true,
    "createdAt": "2030-01-23T23:00:00.123Z",
    "updatedAt": "2030-01-23T23:00:00.123Z",
    "_id": "507f191e810c19729de860ea",
    "active": true,
    "events": [
      "string"
    ],
    "lastRequest": "2030-01-23T23:00:00.123Z",
    "expires": "2030-01-23T23:00:00.123Z",
    "isIntegration": true,
    "integration": "simplyX",
    "deviceSettings": {
      "accessMode": "full",
      "scanGroupId": "507f191e810c19729de860ea"
    },
    "__v": 1
  }
]

GETPUBLIC/api/accessusers/seller

Get associated Seller Id

Request

GET

/api/accessusers/seller

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

const data = await response.json()

Response (200)

{
  "sellerId": "507f191e810c19729de860ea"
}

GETPUBLIC/api/accessusers/events

Get all accessible Events

Returns a list of all events accessible for the device. This endpoint is often used when a user wants to select the event to do the checkin for.

Query parameters

Optional query parameters

Name
includeRootEvents
Type
boolean
Description
Name
includeGroupEvents
Type
boolean
Description

Request

GET

/api/accessusers/events

const response = await fetch('https://vivenu.com/api/accessusers/events?includeRootEvents=true&includeGroupEvents=true', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer {token}',
  },
})

const data = await response.json()

Response (200)

[
  {
    "_id": "507f191e810c19729de860ea",
    "name": "Some fancy Name"
  }
]

GETPUBLIC/api/accessusers/tickets/v2/:eventId

Get Tickets for an Event v2

Returns a paged response of all tickets for a given event. Devices usually fetch and page through this endpoint and persist the results on disk to provide an offline capability.

Query parameters

Optional query parameters

Name
top
Type
number float
Description
A limit on the number of objects to be returned. Can range between 1 and 1000.
Name
skip
Type
number float
Description
The number of objects to skip for the requested result
Name
from
Type
string date-time
Description
An ISO Timestamp to filter tickets where created_at | updated >= $from
Name
until
Type
string date-time
Description
An ISO Timestamp to filter tickets where created_at | updated < $from

Request

GET

/api/accessusers/tickets/v2/:eventId

const response = await fetch('https://vivenu.com/api/accessusers/tickets/v2/507f191e810c19729de860ea?top=10.5&skip=10.5&from=value&until=value', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer {token}',
  },
})

const data = await response.json()

Response (200)

{
  "docs": [
    {
      "_id": "507f191e810c19729de860ea",
      "barcode": "wbf7tkmy",
      "ticketTypeId": "507f191e810c19729de860ea",
      "ticketName": "string",
      "eventId": "507f191e810c19729de860ea",
      "sellerId": "507f191e810c19729de860ea",
      "createdAt": "2030-01-23T23:00:00.123Z",
      "updatedAt": "2030-01-23T23:00:00.123Z",
      "name": "Some fancy Name",
      "priceCategoryId": "507f191e810c19729de860ea",
      "categoryRef": "string",
      "priceCategory": {
        "categoryId": "507f191e810c19729de860ea",
        "description": "string"
      },
      "status": "VALID",
      "area": "string",
      "row": "string",
      "seat": "string",
      "discountId": "507f191e810c19729de860ea",
      "discount": "string",
      "entry": [
        "string"
      ]
    }
  ],
  "total": 1
}

GETPUBLIC/api/accessusers/tickets/:barcode

Get Ticket with barcode

Returns the ticket for a given barcode if existent. This endpoint is typically invoked when a device needs to validate a given barcode in realtime.

Query parameters

Optional query parameters

Name
eventId
Type
string
Description

Request

GET

/api/accessusers/tickets/:barcode

const response = await fetch('https://vivenu.com/api/accessusers/tickets/wbf7tkmy?eventId=507f191e810c19729de860ea', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer {token}',
  },
})

const data = await response.json()

Response (200)

{
  "_id": "507f191e810c19729de860ea",
  "barcode": "wbf7tkmy",
  "ticketTypeId": "507f191e810c19729de860ea",
  "ticketName": "string",
  "eventId": "507f191e810c19729de860ea",
  "sellerId": "507f191e810c19729de860ea",
  "createdAt": "2030-01-23T23:00:00.123Z",
  "updatedAt": "2030-01-23T23:00:00.123Z",
  "name": "Some fancy Name",
  "categoryRef": "string",
  "priceCategoryId": "507f191e810c19729de860ea",
  "priceCategory": {
    "categoryId": "507f191e810c19729de860ea",
    "description": "string"
  },
  "status": "VALID"
}

POSTPUBLIC/api/accessusers/scans/:eventId

Create scans

Payload

Required attributes

Name
barcode
Type
string
Description
The barcode of the ticket
Name
scanned_at
Type
string date-time
Description
An ISO Timestamp indicating when the ticket was scanned.
Name
type
Type
enum(OK, FAIL)
Description
Whether the scan succeeded or failed
Name
direction
Type
enum(IN, OUT)
Description
Indicates in which direction the scan was.

Optional attributes

Name
ticketId
Type
string
Description

Request

POST

/api/accessusers/scans/:eventId

const response = await fetch('https://vivenu.com/api/accessusers/scans/507f191e810c19729de860ea', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer {token}',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(  [
    {
      "barcode": "wbf7tkmy",
      "scanned_at": "2030-01-23T23:00:00.123Z",
      "type": "OK",
      "direction": "IN",
      "ticketId": "507f191e810c19729de860ea"
    }
  ]),
})

const data = await response.json()

Response (200)

{
  "status": "OK"
}