> For the complete documentation index, see [llms.txt](https://help.security.gallagher.com/knowledge-hub/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.security.gallagher.com/knowledge-hub/developer/rest-api/access-zones.md).

# Access Zones

These methods give you read access to Access Zones in the Command Centre database, and let you change their modes, lock them down, and send other overrides.

The first use case below introduces the main entry point. It is a paginated search interface that gives any number of access zones, each containing the fields you ask for in the query.

### Overrides

Note:

1. End-times on overrides are not accurate to the second. Internally, Command Centre converts the end time to a duration, so you may find that submitting end times in the very near future does not have the exact effect you expect.
2. An override without an end time lasts until the next mode change or 'cancel untimed overrides' entry in the access zone's schedule.
3. The end time you set for an override cannot be in the past or more than 24 hours into the future.

### Access Zone status flags

If the access zone is online, its `statusFlags` field may contain one or more of these flags:

* `saltoOutputOnly` means the access zone would be considered unconfigured because it is missing doors, and therefore offline, except that it has a Salto output number assigned to it. That is a normal operational configuration.
* `mobileZone` also means the access zone would be considered unconfigured (missing doors) and therefore offline, except that a mobile reader is able to badge cardholders into it, making it a perfectly useful access zone. It will also have a `secure` flag.
* `lockedDown` means only cardholders with the privilege to enter locked-down zones shall pass. The zone will also be 'secure'. When the lockdown override ends it will return to its previous access mode.
* `usePin` means when you use a card at a reader to unlock the door or at a terminal to control an alarm zone, you will also need your PIN.
* `zoneCountTooHigh` means the zone count is above its maximum.
* `zoneCountTooLow` means the zone count is below its minimum.
* `zoneCountInGrace` means the zone count recently became too low or high.

The following four give the zone's access state. An online access zone will always return one of them.

* `secure` means the doors are locked.
* `dualAuth` means the doors are locked and - depending on configuration - cardholders will need a second credential to open them.
* `codeOrCard` means you can unlock a door either with a card, the zone's access code, or (if suitably configured on the reader) a personal user code. You will not see this flag if the zone is locked down.
* `free` means the zone's doors are unlocked. You will not see this when the zone is locked down.

#### Access Zone flag rules

* If and only if the zone is online and not locked down, there will be exactly one of 'secure', 'dualAuth', 'codeOrCard', or 'free'.
* If and only if the zone is online and locked down, there will be exactly one of 'secure' or 'dualAuth'.
* Because 'saltoOutputOnly' and 'mobileZone' are variations of the unconfigured offline condition, 'saltoOutputOnly' will be alone and only 'secure' will accompany 'mobileZone'.
* If a zone has both a Salto output number and mobile access, only 'saltoOutputOnly' will appear.
* If there is 'zoneCountInGrace' there will always be exactly one of 'zoneCountTooHigh' or 'zoneCountTooLow' (never both).

Using the first three rules above, your test for an access zone being in error is 'secure', 'dualAuth', 'codeOrCard', 'free', 'saltoOutputOnly', and 'mobileZone' all missing.

### Use cases

#### Searching for access zones by name

1. `GET /api`.
2. Follow the link at `features.accessZones.accessZones.href` ↪, appending a search term such as `name=substring` to filter the access zones, and `fields` to tell the server what to return about each. The next section covers those query parameters.
3. Process the results, following the `next` link until there isn't one.

#### Changing an access zone's access mode

1. Find the href for the access zone using the process above.
2. GET it.
3. Find the API URL you require in the `commands` structure of the results, such as `free` or `securePin`, from the detail. Use the `until` variants if you are specifying an end time.
4. POST to that URL. Some require a JSON object (resetting the zone count, and all those with `until` in their command block keys). The others expect an empty body.

#### Finding an access zone's status

1. Find the href for the access zone using the process above, and GET it.
2. Take the `updates` ↪ href from that page. For a version 8.00 server append the query parameter separator (`?` or `&`) then `fields=defaults,zoneCount` if you need the zone count as well as the default status fields. The zone count is included by default in 8.10 and later.
3. GET it.
4. Use the flag rules above to interpret the status flags you receive.
5. Follow the `next` link to stay up to date.

### Licensing

All the POSTs that override items require RESTOverrides.

If you have RESTOverrides but not RESTStatus in 8.60 or later, the GETs return enough information to let you find the item you want to override but they do not return its status. In 8.50 and older, the GET will fail without RESTStatus.

The RESTOverrides and RESTStatus licences do not overlap: to watch the status of an item as well as override it, you will need both.

## Search access zones

> This returns a summary of the access zones matching your search criteria.\
> \
> The result will contain no more than 100 or 1000 access zones (depending on your version),\
> or as many as you asked for; you should follow the \`next\` link, if it\
> is present, to collect the next batch.\
> \
> If your result set is empty it means your operator does not have the privilege to view any\
> access zones, such as 'View Site', 'Edit Site', or 'Override'.  Perhaps there are no access\
> zones in the divisions in which your operator has privileges, or your operator has no\
> privileges at all.\
> \
> When you have loaded them all there will be no \`next\` link.\
> \
> \[Do not code this URL]\(forward-compatibility-hateoas) into your application.  Take\
> it from the 'href' field in the \`features.accessZones.accessZones\` section of \`/api\`.<br>

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"Access Zones","description":"These methods give you read access to Access Zones in the Command Centre database, and\nlet you change their modes, lock them down, and send other overrides.\n\nThe first use case below introduces the main entry point.  It is a paginated search interface\nthat gives any number of access zones, each containing the fields you ask for in the query.\n\n## Overrides\n\nNote:\n\n1. End-times on overrides are not accurate to the second.  Internally, Command Centre\n   converts the end time to a duration, so you may find that submitting end times in\n   the very near future does not have the exact effect you expect.\n2. An override without an end time lasts until the next\n   mode change or 'cancel untimed overrides' entry in the access zone's schedule.\n3. The end time you set for an override cannot be in the past or more than 24 hours into\n   the future.\n\n## Access Zone status flags\n\nIf the access zone is online, its `statusFlags` field may contain one or more of these flags:\n\n- `saltoOutputOnly` means the access zone would be considered unconfigured because it is\n  missing doors, and therefore offline, except that it has a Salto output number assigned to it.\n  That is a normal operational configuration.\n\n- `mobileZone` also means the access zone would be considered unconfigured (missing doors) and\n  therefore offline, except that a mobile reader is able to badge cardholders into it, making it\n  a perfectly useful access zone.  It will also have a `secure` flag.\n\n- `lockedDown` means only cardholders with the privilege to enter locked-down zones shall pass.\n  The zone will also be 'secure'.  When the lockdown override ends it will return to its\n  previous access mode.\n- `usePin` means when you use a card at a reader to unlock the door or at a terminal to control\n  an alarm zone, you will also need your PIN.\n- `zoneCountTooHigh` means the zone count is above its maximum.\n- `zoneCountTooLow` means the zone count is below its minimum.\n- `zoneCountInGrace` means the zone count recently became too low or high.\n\nThe following four give the zone's access state.  An online access zone will always return one\nof them.\n\n- `secure` means the doors are locked.\n- `dualAuth` means the doors are locked and - depending on configuration - cardholders will need\n  a second credential to open them.\n- `codeOrCard` means you can unlock a door either with a card, the zone's access code, or (if\n  suitably configured on the reader) a personal user code.  You will not see this flag if the\n  zone is locked down.\n- `free` means the zone's doors are unlocked.  You will not see this when the zone is locked down.\n\n### Access Zone flag rules\n\n- If and only if the zone is online and not locked down, there will be exactly one of 'secure',\n  'dualAuth', 'codeOrCard', or 'free'.\n\n- If and only if the zone is online and locked down, there will be exactly one of 'secure' or\n  'dualAuth'.\n\n- Because 'saltoOutputOnly' and 'mobileZone' are variations of the unconfigured offline\n  condition, 'saltoOutputOnly' will be alone and only 'secure' will accompany 'mobileZone'.\n\n- If a zone has both a Salto output number and mobile access, only 'saltoOutputOnly' will\n  appear.\n\n- If there is 'zoneCountInGrace' there will always be exactly one of 'zoneCountTooHigh' or\n  'zoneCountTooLow' (never both).\n\nUsing the first three rules above, your test for an access zone being in error is 'secure',\n'dualAuth', 'codeOrCard', 'free', 'saltoOutputOnly', and 'mobileZone' all missing.\n\n## Use cases\n\n### Searching for access zones by name\n 1. `GET /api`.\n 2. Follow the link at `features.accessZones.accessZones.href`\n    [↪](access-zones#get-api-access_zones), appending a search term such as `name=substring` to\n    filter the access zones, and `fields` to tell the server what to return about each.  The\n    next section covers those query parameters.\n 3. Process the results, following the `next` link until there isn't one.\n\n### Changing an access zone's access mode\n 1. Find the href for the access zone using the process above.\n 2. GET it.\n 3. Find the API URL you require in the `commands` structure of the results, such as `free` or\n    `securePin`, from [the detail](models#accesszonedetail).  Use the `until` variants if\n    you are specifying an end time.\n 4. POST to that URL.  Some require a JSON object (resetting the zone count, and all\n     those with `until` in their command block keys).  The others expect an empty body.\n\n### Finding an access zone's status\n1. Find the href for the access zone using the process above, and GET it.\n3. Take the `updates` [↪](access-zones#get-api-access_zones-id-updates) href from that page.  For a\n   version 8.00 server append the query parameter separator (`?` or `&`) then\n   `fields=defaults,zoneCount` if you need the zone count as well as the default status fields.\n   The zone count is included by default in 8.10 and later.\n4. GET it.\n5. Use the flag rules above to interpret the status flags you receive.\n5. Follow the `next` link to stay up to date.\n\n## Licensing\n\nAll the POSTs that override items require RESTOverrides.\n\nIf you have RESTOverrides but not RESTStatus in 8.60 or later, the GETs return enough\ninformation to let you find the item you want to override but they do not return its status.  In\n8.50 and older, the GET will fail without RESTStatus.\n\nThe RESTOverrides and RESTStatus licences do not overlap: to watch the status of an item as well\nas override it, you will need both.\n"}],"servers":[{"url":"https://127.0.0.1:8904"}],"security":[{"API_key":[]},{"basic":[]}],"components":{"securitySchemes":{"API_key":{"type":"apiKey","name":"Authorization","in":"header","description":"\nClients authenticate by including a pre-shared API key in the `Authorization` header of each\nrequest after an authorisation method of `GGL-API-KEY`:\n\n`Authorization: GGL-API-KEY C774-B01F-D695-AA4B-215F-A158-AC22-ADEB`\n\nFor a fuller description see [API authentication](api-authentication).\n"},"basic":{"type":"http","scheme":"basic","description":"This is HTTP Basic authentication using a blank username and the API key as the password.\n\nExample:  `Authorization: Basic OkM3NzQtQjAxRi1ENjk1LUFBNEItMjE1Ri1BMTU4LUFDMjItQURFQg==`\n\nThat example is equivalent to the example in the description of the api_Key method:\nprepending a colon to the API key beginning with `C774` then encoding it into Base64\nproduces the 56 characters beginning with `OkM3`.\n\nThe colon is a separator between a username, which is blank in our case, and the password,\nwhich is our API key.\n\nFor a fuller description see [API authentication](api-authentication)\n"}},"parameters":{"sort":{"name":"sort","in":"query","schema":{"type":"string","enum":["id","name","-id","-name"]},"required":false,"description":"Changes the sort field between database ID and name.\n\nIf you prefix `id` or `name` with a minus sign (ASCII 45), the sort order is reversed.\n\nThere are two very strong reasons to sort by ID:\n\n1. Sorting by name carries a risk of missing or duplicating objects if your result set spans\n   multiple pages and another operator is editing the database while your REST client is\n   enumerating them.  This is known as \"page drift.\"  Sorting by ID does not carry that risk.\n2. Following a `next` link is _dramatically_ quicker when sorting by ID.\n\nWe _strongly_ recommend sorting by ID.  In case you were still in doubt, we will do that by\ndefault in a future version of Command Centre.\n\nThe server silently ignores anything except the options listed here.\n"},"top":{"name":"top","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Limits the results to no more than this many items per page.\n\nOlder versions of Command Centre returned 100 items per page in the absence of this parameter.  That is acceptable for GUI\napplications that will only display the first page, but for integrations that intend to\nproceed through the entire database it causes a lot of chatter.\n\n8.70 and later versions will default to 1000 items per request.  This is about where a graph\nof throughput versus page size begins to level out.\n"},"name":{"name":"name","in":"query","schema":{"type":"string"},"description":"Limits the returned items to those with a name that matches this string.  Without surrounding\nquotes or a percent sign or underscore, it is a substring match; surround the parameter with\ndouble quotes `\"...\"` for an exact match.  Without quotes, a percent sign `%` will match any\nsubstring and an underscore will match any single character.\n\nThe search is always case-insensitive.  Results are undefined if you do a substring search for\nthe empty string (`name=`).  You will receive no items if you search for those with no name\n(`name=\"\"`), as all items must have a name.\n\nSearch parameters are ANDed together.\n"},"division":{"name":"division","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":false,"description":"Limits the returned items to those that are in these divisions.\n\nThat includes all the items in those divisions' child divisions, because Command Centre treats\nitems as though they are also in their division's parent, and its parent, and so on up to the\nroot division.\n\nSeparate the IDs of the divisions in you are interested with commas.  Item IDs are short\nalphanumeric strings, not URLs.\n\nResults are undefined if you provide an ID that is not in the form of a division ID.\n\nSearch parameters are ANDed together.\n"},"directDivision":{"name":"directDivision","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":false,"description":"Restricts items to those whose division is in this list.\n\nUnlike `division=`, it does not follow ancestry.  That means it will limit the search to items\nthat are directly assigned to the divisions you list, whereas `division` (without the\n`direct`) will also include items that are assigned to their descendants.\n\nList the IDs of the divisions you are interested in separated by commas.  Item IDs are short\nalphanumeric strings, not URLs.\n\nBecause this is the first query parameter we added that contains a capital letter, this will\nbe the first time you have had to think about case sensitivity.  `directDivision` works,\n`directdivision` does not.\n\nResults are undefined if you provide an ID that is not in the form of a division ID.\n\nSearch parameters are ANDed together.\n\nAdded in 9.20.\n"},"description":{"name":"description","in":"query","required":false,"schema":{"type":"string"},"description":"Limits the returned items to those with a description that matches this string.  By default it\nis a substring match; surround it with double quotes `\"...\"` for an exact match.  A `_` will\nmatch any single character, and a `%` will match any substring.  With or without quotes,\nhaving either of these wildcards in the string will anchor it at both ends as though you had\nsurrounded it with `\"`.\n\nThe search is always case-insensitive.  Results are undefined if you search for the empty\nstring (`description=` or `description=\"\"`).\n\nSearch parameters are ANDed together.\n"},"pos":{"name":"pos","in":"query","required":false,"schema":{"type":"integer"},"description":"Reserved for internal use.  You may see it in URLs you receive from the server, but you must never add it yourself."},"skip":{"name":"skip","in":"query","required":false,"schema":{"type":"integer"},"description":"Reserved for internal use.  Do not add it to your queries."}},"schemas":{"AccessZoneSummary":{"title":"Access zone summary","description":"`/api/access_zones` returns an array of these.  It is a subset of what you get from an\naccess zone's detail page linked as the href in this object.\n","type":"object","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to an [access zone detail](models#accesszonedetail) object for this access\nzone.  It is also Command Centre's identifier for this access zone:  use it whenever you\nneed to specify an access zone in REST operations.\n"},"id":{"type":"string","readOnly":true,"description":"An alphanumeric identifier, unique to the server.\n\nThis is the ID to use in the `source` parameter of [event\nfilters](events#get-api-events) if you want to limit your events to\nparticular access zones.\n"},"name":{"type":"string"}}}},"responses":{"403nolicence":{"description":"A server running 8.50 or earlier is missing the RESTStatus licence.  A server running 8.60\nor later is missing both the RESTStatus and RESTOverrides licences.  One of those is enough\nfor this API call in 8.60 and later.\n"}}},"paths":{"/api/access_zones":{"get":{"tags":["Access Zones"],"summary":"Search access zones","description":"This returns a summary of the access zones matching your search criteria.\n\nThe result will contain no more than 100 or 1000 access zones (depending on your version),\nor as many as you asked for; you should follow the `next` link, if it\nis present, to collect the next batch.\n\nIf your result set is empty it means your operator does not have the privilege to view any\naccess zones, such as 'View Site', 'Edit Site', or 'Override'.  Perhaps there are no access\nzones in the divisions in which your operator has privileges, or your operator has no\nprivileges at all.\n\nWhen you have loaded them all there will be no `next` link.\n\n[Do not code this URL](forward-compatibility-hateoas) into your application.  Take\nit from the 'href' field in the `features.accessZones.accessZones` section of `/api`.\n","parameters":[{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/top"},{"$ref":"#/components/parameters/name"},{"$ref":"#/components/parameters/division"},{"$ref":"#/components/parameters/directDivision"},{"$ref":"#/components/parameters/description"},{"name":"fields","description":"This instructs the server to return only these fields in the search results.  The values you can list are the same as the field\nnames in the details page.  Using this you can return everything on the summary page that you\nwould find on the details page.  Separate values with commas.\n\nUse the special value `defaults` to return the fields you would have received had you not given\nthe parameter at all.  Obviously only do that if you have more to add.\n\nTreat the string matches as case-sensitive.\n\nIn v8.00 you will receive the href and internal ID even if you did not ask for them.  In 8.10\nand later you will only get what you asked for.  If you are going to send the `fields`\nparameter and need the href or ID, be explicit.\n","schema":{"default":["defaults"],"type":"array","items":{"type":"string","enum":["href","id","name","shortName","description","division","commands","connectedController","doors","zoneCount","statusFlags","statusText","status","notes","updates","defaults"]}},"in":"query","explode":false,"style":"form","required":false},{"$ref":"#/components/parameters/pos"},{"$ref":"#/components/parameters/skip"}],"responses":{"200":{"description":"Success.  See the note in the description about privileges if your result set is empty.\n","content":{"application/json":{"schema":{"description":"This contains an array of access zone summaries, and a `next` link to get more.","type":"object","properties":{"results":{"type":"array","description":"An array of Access Zone summaries.","items":{"$ref":"#/components/schemas/AccessZoneSummary"}},"next":{"type":"object","description":"The link to the next page.  Absent if you have retrieved them all.","properties":{"href":{"type":"string","format":"uri-reference"}}}}}}}},"403":{"$ref":"#/components/responses/403nolicence"}}}}}}
```

## Search targetable access zones

> This returns a list of the access zones to which your operator is allowed to move\
> cardholders, and a special zone you can use as a target to remove a cardholder from all access\
> zones.\
> \
> Like all other paginated queries in this API, the result will contain no more than 100\
> or 1000 access zones (depending on your version), or as many as you asked for more in your\
> request; you should follow the \`next\` link, if it is present, to collect the next batch.\
> \
> When you have loaded them all there will be no \`next\` link.\
> \
> If your result set is empty it means there are no access zones in the divisions in which\
> your operator has the privilege to move cardholders ('Manage Cardholder Location'), or your\
> operator does not have the privilege at all.\
> \
> Do not code this URL into your application.  Take it from the 'href' field in the\
> \`features.cardholders.updateLocationAccessZones\` section of \`/api\`.\
> \
> Added in 8.20.<br>

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"Access Zones","description":"These methods give you read access to Access Zones in the Command Centre database, and\nlet you change their modes, lock them down, and send other overrides.\n\nThe first use case below introduces the main entry point.  It is a paginated search interface\nthat gives any number of access zones, each containing the fields you ask for in the query.\n\n## Overrides\n\nNote:\n\n1. End-times on overrides are not accurate to the second.  Internally, Command Centre\n   converts the end time to a duration, so you may find that submitting end times in\n   the very near future does not have the exact effect you expect.\n2. An override without an end time lasts until the next\n   mode change or 'cancel untimed overrides' entry in the access zone's schedule.\n3. The end time you set for an override cannot be in the past or more than 24 hours into\n   the future.\n\n## Access Zone status flags\n\nIf the access zone is online, its `statusFlags` field may contain one or more of these flags:\n\n- `saltoOutputOnly` means the access zone would be considered unconfigured because it is\n  missing doors, and therefore offline, except that it has a Salto output number assigned to it.\n  That is a normal operational configuration.\n\n- `mobileZone` also means the access zone would be considered unconfigured (missing doors) and\n  therefore offline, except that a mobile reader is able to badge cardholders into it, making it\n  a perfectly useful access zone.  It will also have a `secure` flag.\n\n- `lockedDown` means only cardholders with the privilege to enter locked-down zones shall pass.\n  The zone will also be 'secure'.  When the lockdown override ends it will return to its\n  previous access mode.\n- `usePin` means when you use a card at a reader to unlock the door or at a terminal to control\n  an alarm zone, you will also need your PIN.\n- `zoneCountTooHigh` means the zone count is above its maximum.\n- `zoneCountTooLow` means the zone count is below its minimum.\n- `zoneCountInGrace` means the zone count recently became too low or high.\n\nThe following four give the zone's access state.  An online access zone will always return one\nof them.\n\n- `secure` means the doors are locked.\n- `dualAuth` means the doors are locked and - depending on configuration - cardholders will need\n  a second credential to open them.\n- `codeOrCard` means you can unlock a door either with a card, the zone's access code, or (if\n  suitably configured on the reader) a personal user code.  You will not see this flag if the\n  zone is locked down.\n- `free` means the zone's doors are unlocked.  You will not see this when the zone is locked down.\n\n### Access Zone flag rules\n\n- If and only if the zone is online and not locked down, there will be exactly one of 'secure',\n  'dualAuth', 'codeOrCard', or 'free'.\n\n- If and only if the zone is online and locked down, there will be exactly one of 'secure' or\n  'dualAuth'.\n\n- Because 'saltoOutputOnly' and 'mobileZone' are variations of the unconfigured offline\n  condition, 'saltoOutputOnly' will be alone and only 'secure' will accompany 'mobileZone'.\n\n- If a zone has both a Salto output number and mobile access, only 'saltoOutputOnly' will\n  appear.\n\n- If there is 'zoneCountInGrace' there will always be exactly one of 'zoneCountTooHigh' or\n  'zoneCountTooLow' (never both).\n\nUsing the first three rules above, your test for an access zone being in error is 'secure',\n'dualAuth', 'codeOrCard', 'free', 'saltoOutputOnly', and 'mobileZone' all missing.\n\n## Use cases\n\n### Searching for access zones by name\n 1. `GET /api`.\n 2. Follow the link at `features.accessZones.accessZones.href`\n    [↪](access-zones#get-api-access_zones), appending a search term such as `name=substring` to\n    filter the access zones, and `fields` to tell the server what to return about each.  The\n    next section covers those query parameters.\n 3. Process the results, following the `next` link until there isn't one.\n\n### Changing an access zone's access mode\n 1. Find the href for the access zone using the process above.\n 2. GET it.\n 3. Find the API URL you require in the `commands` structure of the results, such as `free` or\n    `securePin`, from [the detail](models#accesszonedetail).  Use the `until` variants if\n    you are specifying an end time.\n 4. POST to that URL.  Some require a JSON object (resetting the zone count, and all\n     those with `until` in their command block keys).  The others expect an empty body.\n\n### Finding an access zone's status\n1. Find the href for the access zone using the process above, and GET it.\n3. Take the `updates` [↪](access-zones#get-api-access_zones-id-updates) href from that page.  For a\n   version 8.00 server append the query parameter separator (`?` or `&`) then\n   `fields=defaults,zoneCount` if you need the zone count as well as the default status fields.\n   The zone count is included by default in 8.10 and later.\n4. GET it.\n5. Use the flag rules above to interpret the status flags you receive.\n5. Follow the `next` link to stay up to date.\n\n## Licensing\n\nAll the POSTs that override items require RESTOverrides.\n\nIf you have RESTOverrides but not RESTStatus in 8.60 or later, the GETs return enough\ninformation to let you find the item you want to override but they do not return its status.  In\n8.50 and older, the GET will fail without RESTStatus.\n\nThe RESTOverrides and RESTStatus licences do not overlap: to watch the status of an item as well\nas override it, you will need both.\n"}],"servers":[{"url":"https://127.0.0.1:8904"}],"security":[{"API_key":[]},{"basic":[]}],"components":{"securitySchemes":{"API_key":{"type":"apiKey","name":"Authorization","in":"header","description":"\nClients authenticate by including a pre-shared API key in the `Authorization` header of each\nrequest after an authorisation method of `GGL-API-KEY`:\n\n`Authorization: GGL-API-KEY C774-B01F-D695-AA4B-215F-A158-AC22-ADEB`\n\nFor a fuller description see [API authentication](api-authentication).\n"},"basic":{"type":"http","scheme":"basic","description":"This is HTTP Basic authentication using a blank username and the API key as the password.\n\nExample:  `Authorization: Basic OkM3NzQtQjAxRi1ENjk1LUFBNEItMjE1Ri1BMTU4LUFDMjItQURFQg==`\n\nThat example is equivalent to the example in the description of the api_Key method:\nprepending a colon to the API key beginning with `C774` then encoding it into Base64\nproduces the 56 characters beginning with `OkM3`.\n\nThe colon is a separator between a username, which is blank in our case, and the password,\nwhich is our API key.\n\nFor a fuller description see [API authentication](api-authentication)\n"}},"parameters":{"sort":{"name":"sort","in":"query","schema":{"type":"string","enum":["id","name","-id","-name"]},"required":false,"description":"Changes the sort field between database ID and name.\n\nIf you prefix `id` or `name` with a minus sign (ASCII 45), the sort order is reversed.\n\nThere are two very strong reasons to sort by ID:\n\n1. Sorting by name carries a risk of missing or duplicating objects if your result set spans\n   multiple pages and another operator is editing the database while your REST client is\n   enumerating them.  This is known as \"page drift.\"  Sorting by ID does not carry that risk.\n2. Following a `next` link is _dramatically_ quicker when sorting by ID.\n\nWe _strongly_ recommend sorting by ID.  In case you were still in doubt, we will do that by\ndefault in a future version of Command Centre.\n\nThe server silently ignores anything except the options listed here.\n"},"top":{"name":"top","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Limits the results to no more than this many items per page.\n\nOlder versions of Command Centre returned 100 items per page in the absence of this parameter.  That is acceptable for GUI\napplications that will only display the first page, but for integrations that intend to\nproceed through the entire database it causes a lot of chatter.\n\n8.70 and later versions will default to 1000 items per request.  This is about where a graph\nof throughput versus page size begins to level out.\n"},"name":{"name":"name","in":"query","schema":{"type":"string"},"description":"Limits the returned items to those with a name that matches this string.  Without surrounding\nquotes or a percent sign or underscore, it is a substring match; surround the parameter with\ndouble quotes `\"...\"` for an exact match.  Without quotes, a percent sign `%` will match any\nsubstring and an underscore will match any single character.\n\nThe search is always case-insensitive.  Results are undefined if you do a substring search for\nthe empty string (`name=`).  You will receive no items if you search for those with no name\n(`name=\"\"`), as all items must have a name.\n\nSearch parameters are ANDed together.\n"},"division":{"name":"division","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":false,"description":"Limits the returned items to those that are in these divisions.\n\nThat includes all the items in those divisions' child divisions, because Command Centre treats\nitems as though they are also in their division's parent, and its parent, and so on up to the\nroot division.\n\nSeparate the IDs of the divisions in you are interested with commas.  Item IDs are short\nalphanumeric strings, not URLs.\n\nResults are undefined if you provide an ID that is not in the form of a division ID.\n\nSearch parameters are ANDed together.\n"},"directDivision":{"name":"directDivision","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":false,"description":"Restricts items to those whose division is in this list.\n\nUnlike `division=`, it does not follow ancestry.  That means it will limit the search to items\nthat are directly assigned to the divisions you list, whereas `division` (without the\n`direct`) will also include items that are assigned to their descendants.\n\nList the IDs of the divisions you are interested in separated by commas.  Item IDs are short\nalphanumeric strings, not URLs.\n\nBecause this is the first query parameter we added that contains a capital letter, this will\nbe the first time you have had to think about case sensitivity.  `directDivision` works,\n`directdivision` does not.\n\nResults are undefined if you provide an ID that is not in the form of a division ID.\n\nSearch parameters are ANDed together.\n\nAdded in 9.20.\n"},"description":{"name":"description","in":"query","required":false,"schema":{"type":"string"},"description":"Limits the returned items to those with a description that matches this string.  By default it\nis a substring match; surround it with double quotes `\"...\"` for an exact match.  A `_` will\nmatch any single character, and a `%` will match any substring.  With or without quotes,\nhaving either of these wildcards in the string will anchor it at both ends as though you had\nsurrounded it with `\"`.\n\nThe search is always case-insensitive.  Results are undefined if you search for the empty\nstring (`description=` or `description=\"\"`).\n\nSearch parameters are ANDed together.\n"},"pos":{"name":"pos","in":"query","required":false,"schema":{"type":"integer"},"description":"Reserved for internal use.  You may see it in URLs you receive from the server, but you must never add it yourself."},"skip":{"name":"skip","in":"query","required":false,"schema":{"type":"integer"},"description":"Reserved for internal use.  Do not add it to your queries."}},"schemas":{"AccessZoneSummary":{"title":"Access zone summary","description":"`/api/access_zones` returns an array of these.  It is a subset of what you get from an\naccess zone's detail page linked as the href in this object.\n","type":"object","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to an [access zone detail](models#accesszonedetail) object for this access\nzone.  It is also Command Centre's identifier for this access zone:  use it whenever you\nneed to specify an access zone in REST operations.\n"},"id":{"type":"string","readOnly":true,"description":"An alphanumeric identifier, unique to the server.\n\nThis is the ID to use in the `source` parameter of [event\nfilters](events#get-api-events) if you want to limit your events to\nparticular access zones.\n"},"name":{"type":"string"}}}}},"paths":{"/api/access_zones/update_cardholder_location":{"get":{"tags":["Access Zones"],"summary":"Search targetable access zones","description":"This returns a list of the access zones to which your operator is allowed to move\ncardholders, and a special zone you can use as a target to remove a cardholder from all access\nzones.\n\nLike all other paginated queries in this API, the result will contain no more than 100\nor 1000 access zones (depending on your version), or as many as you asked for more in your\nrequest; you should follow the `next` link, if it is present, to collect the next batch.\n\nWhen you have loaded them all there will be no `next` link.\n\nIf your result set is empty it means there are no access zones in the divisions in which\nyour operator has the privilege to move cardholders ('Manage Cardholder Location'), or your\noperator does not have the privilege at all.\n\nDo not code this URL into your application.  Take it from the 'href' field in the\n`features.cardholders.updateLocationAccessZones` section of `/api`.\n\nAdded in 8.20.\n","parameters":[{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/top"},{"$ref":"#/components/parameters/name"},{"$ref":"#/components/parameters/division"},{"$ref":"#/components/parameters/directDivision"},{"$ref":"#/components/parameters/description"},{"name":"fields","description":"This instructs the server to return only these fields in the search results.  The values you can list are the same as the field\nnames in the details page.  Using this you can return everything on the summary page that you\nwould find on the details page.  Separate values with commas.\n\nUse the special value `defaults` to return the fields you would have received had you not given\nthe parameter at all.  Obviously only do that if you have more to add.\n\nTreat the string matches as case-sensitive.\n\nIn v8.00 you will receive the href and internal ID even if you did not ask for them.  In 8.10\nand later you will only get what you asked for.  If you are going to send the `fields`\nparameter and need the href or ID, be explicit.\n","schema":{"default":["defaults"],"type":"array","items":{"type":"string","enum":["href","id","name","shortName","description","division","commands","connectedController","doors","zoneCount","statusFlags","statusText","status","notes","updates","defaults"]}},"in":"query","explode":false,"style":"form","required":false},{"$ref":"#/components/parameters/pos"},{"$ref":"#/components/parameters/skip"}],"responses":{"200":{"description":"Success.  See the note in the description about privileges if your result set is empty.\n","content":{"application/json":{"schema":{"description":"This contains an array of access zones, and a link to a special 'outside the system' access\nzone.  These are the access zones into which your operator has the privilege to move\ncardholders.\n","type":"object","properties":{"results":{"type":"array","description":"This is the same array of Access Zone summaries you would receive from the Access Zone\nsearch GET.\n","items":{"$ref":"#/components/schemas/AccessZoneSummary"}},"outsideOfSystem":{"type":"object","description":"This contains the href you should use to move a cardholder out of all Access Zones.\n","properties":{"href":{"type":"string","format":"uri-reference"}}},"next":{"type":"object","description":"Follow this link to get the next page.  Absent if you have retrieved them all.","properties":{"href":{"type":"string","format":"uri-reference"}}}}}}}},"403":{"description":"The site does not have the RESTCardholders licence."}}}}}}
```

## Get details of an access zone

> This returns the detail of one access zone.\
> \
> Follow the 'href' field in an \[access zone summary]\(models#accesszonesummary) to get\
> here rather than \[building it yourself]\(forward-compatibility-hateoas).<br>

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"Access Zones","description":"These methods give you read access to Access Zones in the Command Centre database, and\nlet you change their modes, lock them down, and send other overrides.\n\nThe first use case below introduces the main entry point.  It is a paginated search interface\nthat gives any number of access zones, each containing the fields you ask for in the query.\n\n## Overrides\n\nNote:\n\n1. End-times on overrides are not accurate to the second.  Internally, Command Centre\n   converts the end time to a duration, so you may find that submitting end times in\n   the very near future does not have the exact effect you expect.\n2. An override without an end time lasts until the next\n   mode change or 'cancel untimed overrides' entry in the access zone's schedule.\n3. The end time you set for an override cannot be in the past or more than 24 hours into\n   the future.\n\n## Access Zone status flags\n\nIf the access zone is online, its `statusFlags` field may contain one or more of these flags:\n\n- `saltoOutputOnly` means the access zone would be considered unconfigured because it is\n  missing doors, and therefore offline, except that it has a Salto output number assigned to it.\n  That is a normal operational configuration.\n\n- `mobileZone` also means the access zone would be considered unconfigured (missing doors) and\n  therefore offline, except that a mobile reader is able to badge cardholders into it, making it\n  a perfectly useful access zone.  It will also have a `secure` flag.\n\n- `lockedDown` means only cardholders with the privilege to enter locked-down zones shall pass.\n  The zone will also be 'secure'.  When the lockdown override ends it will return to its\n  previous access mode.\n- `usePin` means when you use a card at a reader to unlock the door or at a terminal to control\n  an alarm zone, you will also need your PIN.\n- `zoneCountTooHigh` means the zone count is above its maximum.\n- `zoneCountTooLow` means the zone count is below its minimum.\n- `zoneCountInGrace` means the zone count recently became too low or high.\n\nThe following four give the zone's access state.  An online access zone will always return one\nof them.\n\n- `secure` means the doors are locked.\n- `dualAuth` means the doors are locked and - depending on configuration - cardholders will need\n  a second credential to open them.\n- `codeOrCard` means you can unlock a door either with a card, the zone's access code, or (if\n  suitably configured on the reader) a personal user code.  You will not see this flag if the\n  zone is locked down.\n- `free` means the zone's doors are unlocked.  You will not see this when the zone is locked down.\n\n### Access Zone flag rules\n\n- If and only if the zone is online and not locked down, there will be exactly one of 'secure',\n  'dualAuth', 'codeOrCard', or 'free'.\n\n- If and only if the zone is online and locked down, there will be exactly one of 'secure' or\n  'dualAuth'.\n\n- Because 'saltoOutputOnly' and 'mobileZone' are variations of the unconfigured offline\n  condition, 'saltoOutputOnly' will be alone and only 'secure' will accompany 'mobileZone'.\n\n- If a zone has both a Salto output number and mobile access, only 'saltoOutputOnly' will\n  appear.\n\n- If there is 'zoneCountInGrace' there will always be exactly one of 'zoneCountTooHigh' or\n  'zoneCountTooLow' (never both).\n\nUsing the first three rules above, your test for an access zone being in error is 'secure',\n'dualAuth', 'codeOrCard', 'free', 'saltoOutputOnly', and 'mobileZone' all missing.\n\n## Use cases\n\n### Searching for access zones by name\n 1. `GET /api`.\n 2. Follow the link at `features.accessZones.accessZones.href`\n    [↪](access-zones#get-api-access_zones), appending a search term such as `name=substring` to\n    filter the access zones, and `fields` to tell the server what to return about each.  The\n    next section covers those query parameters.\n 3. Process the results, following the `next` link until there isn't one.\n\n### Changing an access zone's access mode\n 1. Find the href for the access zone using the process above.\n 2. GET it.\n 3. Find the API URL you require in the `commands` structure of the results, such as `free` or\n    `securePin`, from [the detail](models#accesszonedetail).  Use the `until` variants if\n    you are specifying an end time.\n 4. POST to that URL.  Some require a JSON object (resetting the zone count, and all\n     those with `until` in their command block keys).  The others expect an empty body.\n\n### Finding an access zone's status\n1. Find the href for the access zone using the process above, and GET it.\n3. Take the `updates` [↪](access-zones#get-api-access_zones-id-updates) href from that page.  For a\n   version 8.00 server append the query parameter separator (`?` or `&`) then\n   `fields=defaults,zoneCount` if you need the zone count as well as the default status fields.\n   The zone count is included by default in 8.10 and later.\n4. GET it.\n5. Use the flag rules above to interpret the status flags you receive.\n5. Follow the `next` link to stay up to date.\n\n## Licensing\n\nAll the POSTs that override items require RESTOverrides.\n\nIf you have RESTOverrides but not RESTStatus in 8.60 or later, the GETs return enough\ninformation to let you find the item you want to override but they do not return its status.  In\n8.50 and older, the GET will fail without RESTStatus.\n\nThe RESTOverrides and RESTStatus licences do not overlap: to watch the status of an item as well\nas override it, you will need both.\n"}],"servers":[{"url":"https://127.0.0.1:8904"}],"security":[{"API_key":[]},{"basic":[]}],"components":{"securitySchemes":{"API_key":{"type":"apiKey","name":"Authorization","in":"header","description":"\nClients authenticate by including a pre-shared API key in the `Authorization` header of each\nrequest after an authorisation method of `GGL-API-KEY`:\n\n`Authorization: GGL-API-KEY C774-B01F-D695-AA4B-215F-A158-AC22-ADEB`\n\nFor a fuller description see [API authentication](api-authentication).\n"},"basic":{"type":"http","scheme":"basic","description":"This is HTTP Basic authentication using a blank username and the API key as the password.\n\nExample:  `Authorization: Basic OkM3NzQtQjAxRi1ENjk1LUFBNEItMjE1Ri1BMTU4LUFDMjItQURFQg==`\n\nThat example is equivalent to the example in the description of the api_Key method:\nprepending a colon to the API key beginning with `C774` then encoding it into Base64\nproduces the 56 characters beginning with `OkM3`.\n\nThe colon is a separator between a username, which is blank in our case, and the password,\nwhich is our API key.\n\nFor a fuller description see [API authentication](api-authentication)\n"}},"schemas":{"AccessZoneDetail":{"title":"Access zone detail","description":"[/api/access_zones/{id}](access-zones#get-api-access_zones-id-) returns one of these.\n\nAs well as the properties below, it contains a block called `doors`.  This is reserved for\nfuture development and its behaviour could change in later versions of Command Centre.\n","allOf":[{"$ref":"#/components/schemas/AccessZoneSummary"},{"type":"object","properties":{"description":{"type":"string"},"division":{"type":"object","description":"The division containing this Access Zone."},"doors":{"type":"array","description":"A list containing names of and links to the doors that control entry to this access zone.","items":{"type":"object","properties":{"name":{"type":"string"},"href":{"type":"string","format":"uri-reference","description":"This is the link to the [door's detail](models#doordetail), which\ncontains a return link back to this page in either its `entryAccessZone` or\n`exitAccessZone` field.\n"}}}},"zoneCount":{"readOnly":true,"type":"integer","description":"The number of cardholders in the zone, according to its zone counting configuration.\n\nAn access zone's count is part of its state, so [all that reading](item-status)\napplies here too.  The authoritative source is the zone's hardware controller, so the\nREST server only has it if it is monitoring it for another reason.  If it is not, it\nreturns a zero.\n\nThat is why zone counts are not in the default set of fields.  You can ask for them\nusing the 'fields' parameter, but you risk receiving a zero, so the recommended way is\nto follow the Access Zone's 'updates' link with `fields=defaults,zoneCount` appended\nafter the appropriate query parameter separator.\n\nA zone count is correct iff the access zone is online:  the status flags must contain\none of 'secure', 'dualAuth', 'codeOrCard', or 'free'.  Even then, the zone count could\nbe a minute out of date (depending on a server property that determines how long a\nhardware item can be silent before the server calls it offline).\n"},"notes":{"type":"string","description":"Because of their potential size, notes are only available by request.  Use the 'fields'\nparameter:\n\n`?fields=defaults,notes,...`\n"},"shortName":{"type":"string","maxLength":16,"description":"Short names are not displayed by default.  You must ask for them using the\n'fields' parameter:\n\n`?fields=shortname,...`.\n"},"updates":{"type":"object","properties":{"href":{"type":"string","format":"uri-reference"}},"description":"Follow the URL in the href inside this block to receive the item's current status, then follow\nthe `next` link in the results to long poll for changes to that status.\n\nThis method only monitors one item at a time.  To monitor the status of many items, use the\n[status-monitoring routes](#?route=post-/api/items/updates).\n\nUpdate pages take the same `fields` parameter as summary and details pages.  You should use\nthat to request all the fields you need in the update.\n","readOnly":true},"statusFlags":{"type":"array","items":{"type":"string"},"description":"The search and details pages do not return status flags by default, because an item's status\nis unknown until something is monitoring it.  If you want status flags on the search and\ndetails pages you must ask for them using the `fields` parameter, but our advice is to monitor\nthem using [status subscriptions](items#status-subscriptions) if you are running 8.30 or\nlater, otherwise the item's `updates` link.  See the [item status](item-status) section\nfor a full description of how to stay up to date with item status, and this item's\nintroduction in the Operations section for what flags this item might return and what they\nmean.\n","readOnly":true},"connectedController":{"type":"object","description":"This block describes this item's hardware controller.\n\nRetrieving it takes a little more time than the other fields so only ask for it if you\nneed it.\n\nAdded in 8.50.\n","properties":{"name":{"type":"string"},"href":{"type":"string","format":"uri-reference","description":"This is the REST API's identifier for the hardware controller.  It is only an\nidentifier, not a usable URL, because there is no interface for hardware\ncontrollers.  GETting the URL will return a 404.\n"},"id":{"type":"string","description":"An alphanumeric identifier, unique to the server.  This is the ID to use in the `source`\nparameter of [event filters](events#get-api-events).\n"}}},"commands":{"type":"object","readOnly":true,"description":"A block of commands, each represented by a block containing an href that accepts a\nPOST that will send an override to the access zone, changing its state.\n\nIt will be missing if your operator does not have a privilege that allows overriding\nthe access zone (examples of which are in the documentation for the POSTs).\n","properties":{"free":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-free) to this to override the\nzone into 'free - no PIN' access mode until the next scheduled change.\n","type":"string","format":"uri-reference"}}},"freeUntil":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-free) to this to override the\nzone into 'free - no PIN' access mode for a fixed time.\n","type":"string","format":"uri-reference"}}},"freePin":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-free) to this to override the\nzone into 'free - PIN' access mode until the next scheduled change.\n","type":"string","format":"uri-reference"}}},"freePinUntil":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-free) to this to override the\nzone into 'free - PIN' access mode for a fixed time.\n","type":"string","format":"uri-reference"}}},"secure":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-secure) to this to override the\nzone into 'secure - no PIN' access mode until the next scheduled change.\n","type":"string","format":"uri-reference"}}},"secureUntil":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-secure) to this to override the\nzone into 'secure - no PIN' access mode for a fixed time.\n","type":"string","format":"uri-reference"}}},"securePin":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-secure) to this to override the\nzone into 'secure - PIN' access mode until the next scheduled change.\n","type":"string","format":"uri-reference"}}},"securePinUntil":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-secure) to this to override the\nzone into 'secure - PIN' access mode for a fixed time.\n","type":"string","format":"uri-reference"}}},"codeOnly":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-code_only) to this to override\nthe zone into 'code or card - no PIN' access mode until the next scheduled\nchange.\n","type":"string","format":"uri-reference"}}},"codeOnlyUntil":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-code_only) to this to override\nthe zone into 'code or card - no PIN' access mode for a fixed time.\n","type":"string","format":"uri-reference"}}},"codeOnlyPin":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-code_only) to this to override\nthe zone into 'code or card - PIN' access mode until the next scheduled\nchange.\n","type":"string","format":"uri-reference"}}},"codeOnlyPinUntil":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-code_only) to this to override\nthe zone into 'code or card - PIN' access mode for a fixed time.\n","type":"string","format":"uri-reference"}}},"dualAuth":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-dual_auth) to this to override\nthe zone into 'dual auth - no PIN' access mode until the next scheduled\nchange.\n","type":"string","format":"uri-reference"}}},"dualAuthUntil":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-dual_auth) to this to override\nthe zone into 'dual auth - no PIN' access mode for a fixed time.\n","type":"string","format":"uri-reference"}}},"dualAuthPin":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-dual_auth) to this to override\nthe zone into 'dual auth - PIN' access mode until the next scheduled change.\n","type":"string","format":"uri-reference"}}},"dualAuthPinUntil":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-dual_auth) to this to override\nthe zone into 'dual auth - PIN' access mode for a fixed time.\n","type":"string","format":"uri-reference"}}},"forgiveAntiPassback":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-forgive_anti_passback) to this\nto forgive anti-passback for all cardholders in the zone.\n","type":"string","format":"uri-reference"}}},"setZoneCount":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-set_zone_count) to this to set the\nzone's cardholder count.\n","type":"string","format":"uri-reference"}}},"lockDown":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-lock_down) to this to set the zone\ninto lockdown mode.\n","type":"string","format":"uri-reference"}}},"cancelLockDown":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-cancel_lock_down) to this to cancel\nlockdown on the zone, returning it to its scheduled mode.\n","type":"string","format":"uri-reference"}}},"cancel":{"type":"object","properties":{"href":{"description":"[POST](access-zones#post-api-access_zones-id-cancel) to this to cancel an\nactive override on the zone, returning it to its scheduled mode.  This will\nnot affect a lockdown.\n","type":"string","format":"uri-reference"}}}}}}}]},"AccessZoneSummary":{"title":"Access zone summary","description":"`/api/access_zones` returns an array of these.  It is a subset of what you get from an\naccess zone's detail page linked as the href in this object.\n","type":"object","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to an [access zone detail](models#accesszonedetail) object for this access\nzone.  It is also Command Centre's identifier for this access zone:  use it whenever you\nneed to specify an access zone in REST operations.\n"},"id":{"type":"string","readOnly":true,"description":"An alphanumeric identifier, unique to the server.\n\nThis is the ID to use in the `source` parameter of [event\nfilters](events#get-api-events) if you want to limit your events to\nparticular access zones.\n"},"name":{"type":"string"}}}},"responses":{"403nolicence":{"description":"A server running 8.50 or earlier is missing the RESTStatus licence.  A server running 8.60\nor later is missing both the RESTStatus and RESTOverrides licences.  One of those is enough\nfor this API call in 8.60 and later.\n"},"404accesszone":{"description":"The request's URL does not represent an access zone, or the operator does not have a privilege\non the zone's division that allows viewing access zones, such as 'View Site', 'Edit Site', or\n'Override'.\n"}}},"paths":{"/api/access_zones/{id}":{"get":{"tags":["Access Zones"],"summary":"Get details of an access zone","description":"This returns the detail of one access zone.\n\nFollow the 'href' field in an [access zone summary](models#accesszonesummary) to get\nhere rather than [building it yourself](forward-compatibility-hateoas).\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"fields","in":"query","explode":false,"description":"This instructs the server to return only these fields in the details page instead of the default set.  The values you can list\nare the same as the field names you would see in the results.  Use it to cut back on the size\nof the response.  Separate values with commas.\n\nTreat the string matches as case-sensitive.\n\nIn v8.00 you will receive the href and internal ID even if you did not ask for them.  In 8.10\nand later you will only get what you asked for.  If you are going to send the `fields`\nparameter and need the href or ID, be explicit.\n","schema":{"type":"string","enum":["href","id","name","shortName","description","division","commands","connectedController","doors","zoneCount","statusFlags","statusText","status","notes","updates"]}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessZoneDetail"}}}},"403":{"$ref":"#/components/responses/403nolicence"},"404":{"$ref":"#/components/responses/404accesszone"}}}}}}
```

## Set access zone free

> Sends an override to an access zone to change its mode to 'free - no PIN', meaning the doors\
> will be free and you will not need a PIN to perform an override on a terminal.\
> \
> Take this URL from the \`commands\` block of an access zone.  In there is a block called\
> \`free\`, containing a field \`href\`.  That is the URL of this method.\
> \
> The URL from \`commands.freePin.href\` (as opposed to "free" without the "Pin") will send an override to an\
> access zone to change its mode to 'free - PIN', meaning you \_will\_ need a PIN on a terminal.\
> \
> If you do not give the override an end time in the body it will remain in place until the\
> next scheduled change.<br>

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"Access Zones","description":"These methods give you read access to Access Zones in the Command Centre database, and\nlet you change their modes, lock them down, and send other overrides.\n\nThe first use case below introduces the main entry point.  It is a paginated search interface\nthat gives any number of access zones, each containing the fields you ask for in the query.\n\n## Overrides\n\nNote:\n\n1. End-times on overrides are not accurate to the second.  Internally, Command Centre\n   converts the end time to a duration, so you may find that submitting end times in\n   the very near future does not have the exact effect you expect.\n2. An override without an end time lasts until the next\n   mode change or 'cancel untimed overrides' entry in the access zone's schedule.\n3. The end time you set for an override cannot be in the past or more than 24 hours into\n   the future.\n\n## Access Zone status flags\n\nIf the access zone is online, its `statusFlags` field may contain one or more of these flags:\n\n- `saltoOutputOnly` means the access zone would be considered unconfigured because it is\n  missing doors, and therefore offline, except that it has a Salto output number assigned to it.\n  That is a normal operational configuration.\n\n- `mobileZone` also means the access zone would be considered unconfigured (missing doors) and\n  therefore offline, except that a mobile reader is able to badge cardholders into it, making it\n  a perfectly useful access zone.  It will also have a `secure` flag.\n\n- `lockedDown` means only cardholders with the privilege to enter locked-down zones shall pass.\n  The zone will also be 'secure'.  When the lockdown override ends it will return to its\n  previous access mode.\n- `usePin` means when you use a card at a reader to unlock the door or at a terminal to control\n  an alarm zone, you will also need your PIN.\n- `zoneCountTooHigh` means the zone count is above its maximum.\n- `zoneCountTooLow` means the zone count is below its minimum.\n- `zoneCountInGrace` means the zone count recently became too low or high.\n\nThe following four give the zone's access state.  An online access zone will always return one\nof them.\n\n- `secure` means the doors are locked.\n- `dualAuth` means the doors are locked and - depending on configuration - cardholders will need\n  a second credential to open them.\n- `codeOrCard` means you can unlock a door either with a card, the zone's access code, or (if\n  suitably configured on the reader) a personal user code.  You will not see this flag if the\n  zone is locked down.\n- `free` means the zone's doors are unlocked.  You will not see this when the zone is locked down.\n\n### Access Zone flag rules\n\n- If and only if the zone is online and not locked down, there will be exactly one of 'secure',\n  'dualAuth', 'codeOrCard', or 'free'.\n\n- If and only if the zone is online and locked down, there will be exactly one of 'secure' or\n  'dualAuth'.\n\n- Because 'saltoOutputOnly' and 'mobileZone' are variations of the unconfigured offline\n  condition, 'saltoOutputOnly' will be alone and only 'secure' will accompany 'mobileZone'.\n\n- If a zone has both a Salto output number and mobile access, only 'saltoOutputOnly' will\n  appear.\n\n- If there is 'zoneCountInGrace' there will always be exactly one of 'zoneCountTooHigh' or\n  'zoneCountTooLow' (never both).\n\nUsing the first three rules above, your test for an access zone being in error is 'secure',\n'dualAuth', 'codeOrCard', 'free', 'saltoOutputOnly', and 'mobileZone' all missing.\n\n## Use cases\n\n### Searching for access zones by name\n 1. `GET /api`.\n 2. Follow the link at `features.accessZones.accessZones.href`\n    [↪](access-zones#get-api-access_zones), appending a search term such as `name=substring` to\n    filter the access zones, and `fields` to tell the server what to return about each.  The\n    next section covers those query parameters.\n 3. Process the results, following the `next` link until there isn't one.\n\n### Changing an access zone's access mode\n 1. Find the href for the access zone using the process above.\n 2. GET it.\n 3. Find the API URL you require in the `commands` structure of the results, such as `free` or\n    `securePin`, from [the detail](models#accesszonedetail).  Use the `until` variants if\n    you are specifying an end time.\n 4. POST to that URL.  Some require a JSON object (resetting the zone count, and all\n     those with `until` in their command block keys).  The others expect an empty body.\n\n### Finding an access zone's status\n1. Find the href for the access zone using the process above, and GET it.\n3. Take the `updates` [↪](access-zones#get-api-access_zones-id-updates) href from that page.  For a\n   version 8.00 server append the query parameter separator (`?` or `&`) then\n   `fields=defaults,zoneCount` if you need the zone count as well as the default status fields.\n   The zone count is included by default in 8.10 and later.\n4. GET it.\n5. Use the flag rules above to interpret the status flags you receive.\n5. Follow the `next` link to stay up to date.\n\n## Licensing\n\nAll the POSTs that override items require RESTOverrides.\n\nIf you have RESTOverrides but not RESTStatus in 8.60 or later, the GETs return enough\ninformation to let you find the item you want to override but they do not return its status.  In\n8.50 and older, the GET will fail without RESTStatus.\n\nThe RESTOverrides and RESTStatus licences do not overlap: to watch the status of an item as well\nas override it, you will need both.\n"}],"servers":[{"url":"https://127.0.0.1:8904"}],"security":[{"API_key":[]},{"basic":[]}],"components":{"securitySchemes":{"API_key":{"type":"apiKey","name":"Authorization","in":"header","description":"\nClients authenticate by including a pre-shared API key in the `Authorization` header of each\nrequest after an authorisation method of `GGL-API-KEY`:\n\n`Authorization: GGL-API-KEY C774-B01F-D695-AA4B-215F-A158-AC22-ADEB`\n\nFor a fuller description see [API authentication](api-authentication).\n"},"basic":{"type":"http","scheme":"basic","description":"This is HTTP Basic authentication using a blank username and the API key as the password.\n\nExample:  `Authorization: Basic OkM3NzQtQjAxRi1ENjk1LUFBNEItMjE1Ri1BMTU4LUFDMjItQURFQg==`\n\nThat example is equivalent to the example in the description of the api_Key method:\nprepending a colon to the API key beginning with `C774` then encoding it into Base64\nproduces the 56 characters beginning with `OkM3`.\n\nThe colon is a separator between a username, which is blank in our case, and the password,\nwhich is our API key.\n\nFor a fuller description see [API authentication](api-authentication)\n"}},"parameters":{"requested_by":{"name":"requested_by","in":"query","required":false,"schema":{"type":"string"},"description":"Attributes this override to the cardholder with this ID rather than the REST operator.\nPrivilege checks will use the operator as normal, but event monitors and reports will state\nthat the person responsible for the override was the attributed cardholder, not the REST\noperator.  The REST operator will appear in a special mention in the event's details.\n\nFirst available in 8.70.  Versions older than 8.70 will ignore the parameter, leaving the\noverride attributed to the REST operator.\n"}},"requestBodies":{"OverrideEndTime":{"description":"Put this in the body of override POSTs to set the time at which the override should cease.\nThe API will reject the override if the string is not empty and it cannot parse it into a\ndate-time, but it will treat the override as having no end time if you misspell 'endTime'\nor if you send a blank string.\n\nCommand Centre computes an override's duration to a whole number of minutes with a minimum\nof one.  That means that a timed override will always end at a multiple of sixty seconds\nfrom the time the hardware receives the override request, which means the override will end\nwithin thirty seconds of the time you supplied here.  In versions older than 8.80, the\ndiscrepancy may be up to a minute.\n\nCareful observation of overrides submitted from the Configuration client and from the API\nwill reveal that they use different rounding methods.  Be assured, both result in overrides\nending within a minute of the requested time.\n","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"endTime":{"type":"string","format":"date-time"}}}}}}},"responses":{"400badbody":{"description":"The server could not parse the POST parameters.  There could be a syntax error in your JSON.\n"},"403accesszoneoverride":{"description":"The site does not have the RESTOverrides licence (in which case the body of the result will\nsay so), or the operator does not have a privilege that allows overriding access zones (such\nas 'Override').\n"}}},"paths":{"/api/access_zones/{id}/free":{"post":{"tags":["Access Zones"],"summary":"Set access zone free","description":"Sends an override to an access zone to change its mode to 'free - no PIN', meaning the doors\nwill be free and you will not need a PIN to perform an override on a terminal.\n\nTake this URL from the `commands` block of an access zone.  In there is a block called\n`free`, containing a field `href`.  That is the URL of this method.\n\nThe URL from `commands.freePin.href` (as opposed to \"free\" without the \"Pin\") will send an override to an\naccess zone to change its mode to 'free - PIN', meaning you _will_ need a PIN on a terminal.\n\nIf you do not give the override an end time in the body it will remain in place until the\nnext scheduled change.\n","parameters":[{"name":"id","in":"path","description":"The ID of the access zone.","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/requested_by"}],"requestBody":{"$ref":"#/components/requestBodies/OverrideEndTime"},"responses":{"204":{"description":"Success."},"400":{"$ref":"#/components/responses/400badbody"},"403":{"$ref":"#/components/responses/403accesszoneoverride"}}}}}}
```

## Set access zone secure

> Sends an override to an access zone to change its mode to 'secure - no PIN', meaning you\
> will need a card, but not a PIN, to open its doors or perform overrides on terminals.\
> \
> Take this URL from the \`commands\` block of an access zone.  In there is a block called\
> \`secure\`, containing a field \`href\`.  That is the URL of this method.\
> \
> The URL from \`commands.securePin.href\` (as opposed to \`secure\` without the \`Pin\`) will send an override to an\
> access zone to change its mode to 'secure - PIN', meaning you \_will\_ need a PIN on a terminal.\
> \
> If you do not give the override an end time in the body, it will remain in place until the\
> next scheduled change.<br>

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"Access Zones","description":"These methods give you read access to Access Zones in the Command Centre database, and\nlet you change their modes, lock them down, and send other overrides.\n\nThe first use case below introduces the main entry point.  It is a paginated search interface\nthat gives any number of access zones, each containing the fields you ask for in the query.\n\n## Overrides\n\nNote:\n\n1. End-times on overrides are not accurate to the second.  Internally, Command Centre\n   converts the end time to a duration, so you may find that submitting end times in\n   the very near future does not have the exact effect you expect.\n2. An override without an end time lasts until the next\n   mode change or 'cancel untimed overrides' entry in the access zone's schedule.\n3. The end time you set for an override cannot be in the past or more than 24 hours into\n   the future.\n\n## Access Zone status flags\n\nIf the access zone is online, its `statusFlags` field may contain one or more of these flags:\n\n- `saltoOutputOnly` means the access zone would be considered unconfigured because it is\n  missing doors, and therefore offline, except that it has a Salto output number assigned to it.\n  That is a normal operational configuration.\n\n- `mobileZone` also means the access zone would be considered unconfigured (missing doors) and\n  therefore offline, except that a mobile reader is able to badge cardholders into it, making it\n  a perfectly useful access zone.  It will also have a `secure` flag.\n\n- `lockedDown` means only cardholders with the privilege to enter locked-down zones shall pass.\n  The zone will also be 'secure'.  When the lockdown override ends it will return to its\n  previous access mode.\n- `usePin` means when you use a card at a reader to unlock the door or at a terminal to control\n  an alarm zone, you will also need your PIN.\n- `zoneCountTooHigh` means the zone count is above its maximum.\n- `zoneCountTooLow` means the zone count is below its minimum.\n- `zoneCountInGrace` means the zone count recently became too low or high.\n\nThe following four give the zone's access state.  An online access zone will always return one\nof them.\n\n- `secure` means the doors are locked.\n- `dualAuth` means the doors are locked and - depending on configuration - cardholders will need\n  a second credential to open them.\n- `codeOrCard` means you can unlock a door either with a card, the zone's access code, or (if\n  suitably configured on the reader) a personal user code.  You will not see this flag if the\n  zone is locked down.\n- `free` means the zone's doors are unlocked.  You will not see this when the zone is locked down.\n\n### Access Zone flag rules\n\n- If and only if the zone is online and not locked down, there will be exactly one of 'secure',\n  'dualAuth', 'codeOrCard', or 'free'.\n\n- If and only if the zone is online and locked down, there will be exactly one of 'secure' or\n  'dualAuth'.\n\n- Because 'saltoOutputOnly' and 'mobileZone' are variations of the unconfigured offline\n  condition, 'saltoOutputOnly' will be alone and only 'secure' will accompany 'mobileZone'.\n\n- If a zone has both a Salto output number and mobile access, only 'saltoOutputOnly' will\n  appear.\n\n- If there is 'zoneCountInGrace' there will always be exactly one of 'zoneCountTooHigh' or\n  'zoneCountTooLow' (never both).\n\nUsing the first three rules above, your test for an access zone being in error is 'secure',\n'dualAuth', 'codeOrCard', 'free', 'saltoOutputOnly', and 'mobileZone' all missing.\n\n## Use cases\n\n### Searching for access zones by name\n 1. `GET /api`.\n 2. Follow the link at `features.accessZones.accessZones.href`\n    [↪](access-zones#get-api-access_zones), appending a search term such as `name=substring` to\n    filter the access zones, and `fields` to tell the server what to return about each.  The\n    next section covers those query parameters.\n 3. Process the results, following the `next` link until there isn't one.\n\n### Changing an access zone's access mode\n 1. Find the href for the access zone using the process above.\n 2. GET it.\n 3. Find the API URL you require in the `commands` structure of the results, such as `free` or\n    `securePin`, from [the detail](models#accesszonedetail).  Use the `until` variants if\n    you are specifying an end time.\n 4. POST to that URL.  Some require a JSON object (resetting the zone count, and all\n     those with `until` in their command block keys).  The others expect an empty body.\n\n### Finding an access zone's status\n1. Find the href for the access zone using the process above, and GET it.\n3. Take the `updates` [↪](access-zones#get-api-access_zones-id-updates) href from that page.  For a\n   version 8.00 server append the query parameter separator (`?` or `&`) then\n   `fields=defaults,zoneCount` if you need the zone count as well as the default status fields.\n   The zone count is included by default in 8.10 and later.\n4. GET it.\n5. Use the flag rules above to interpret the status flags you receive.\n5. Follow the `next` link to stay up to date.\n\n## Licensing\n\nAll the POSTs that override items require RESTOverrides.\n\nIf you have RESTOverrides but not RESTStatus in 8.60 or later, the GETs return enough\ninformation to let you find the item you want to override but they do not return its status.  In\n8.50 and older, the GET will fail without RESTStatus.\n\nThe RESTOverrides and RESTStatus licences do not overlap: to watch the status of an item as well\nas override it, you will need both.\n"}],"servers":[{"url":"https://127.0.0.1:8904"}],"security":[{"API_key":[]},{"basic":[]}],"components":{"securitySchemes":{"API_key":{"type":"apiKey","name":"Authorization","in":"header","description":"\nClients authenticate by including a pre-shared API key in the `Authorization` header of each\nrequest after an authorisation method of `GGL-API-KEY`:\n\n`Authorization: GGL-API-KEY C774-B01F-D695-AA4B-215F-A158-AC22-ADEB`\n\nFor a fuller description see [API authentication](api-authentication).\n"},"basic":{"type":"http","scheme":"basic","description":"This is HTTP Basic authentication using a blank username and the API key as the password.\n\nExample:  `Authorization: Basic OkM3NzQtQjAxRi1ENjk1LUFBNEItMjE1Ri1BMTU4LUFDMjItQURFQg==`\n\nThat example is equivalent to the example in the description of the api_Key method:\nprepending a colon to the API key beginning with `C774` then encoding it into Base64\nproduces the 56 characters beginning with `OkM3`.\n\nThe colon is a separator between a username, which is blank in our case, and the password,\nwhich is our API key.\n\nFor a fuller description see [API authentication](api-authentication)\n"}},"parameters":{"requested_by":{"name":"requested_by","in":"query","required":false,"schema":{"type":"string"},"description":"Attributes this override to the cardholder with this ID rather than the REST operator.\nPrivilege checks will use the operator as normal, but event monitors and reports will state\nthat the person responsible for the override was the attributed cardholder, not the REST\noperator.  The REST operator will appear in a special mention in the event's details.\n\nFirst available in 8.70.  Versions older than 8.70 will ignore the parameter, leaving the\noverride attributed to the REST operator.\n"}},"requestBodies":{"OverrideEndTime":{"description":"Put this in the body of override POSTs to set the time at which the override should cease.\nThe API will reject the override if the string is not empty and it cannot parse it into a\ndate-time, but it will treat the override as having no end time if you misspell 'endTime'\nor if you send a blank string.\n\nCommand Centre computes an override's duration to a whole number of minutes with a minimum\nof one.  That means that a timed override will always end at a multiple of sixty seconds\nfrom the time the hardware receives the override request, which means the override will end\nwithin thirty seconds of the time you supplied here.  In versions older than 8.80, the\ndiscrepancy may be up to a minute.\n\nCareful observation of overrides submitted from the Configuration client and from the API\nwill reveal that they use different rounding methods.  Be assured, both result in overrides\nending within a minute of the requested time.\n","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"endTime":{"type":"string","format":"date-time"}}}}}}},"responses":{"400badbody":{"description":"The server could not parse the POST parameters.  There could be a syntax error in your JSON.\n"},"403accesszoneoverride":{"description":"The site does not have the RESTOverrides licence (in which case the body of the result will\nsay so), or the operator does not have a privilege that allows overriding access zones (such\nas 'Override').\n"}}},"paths":{"/api/access_zones/{id}/secure":{"post":{"tags":["Access Zones"],"summary":"Set access zone secure","description":"Sends an override to an access zone to change its mode to 'secure - no PIN', meaning you\nwill need a card, but not a PIN, to open its doors or perform overrides on terminals.\n\nTake this URL from the `commands` block of an access zone.  In there is a block called\n`secure`, containing a field `href`.  That is the URL of this method.\n\nThe URL from `commands.securePin.href` (as opposed to `secure` without the `Pin`) will send an override to an\naccess zone to change its mode to 'secure - PIN', meaning you _will_ need a PIN on a terminal.\n\nIf you do not give the override an end time in the body, it will remain in place until the\nnext scheduled change.\n","parameters":[{"name":"id","in":"path","description":"The ID of the access zone.","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/requested_by"}],"requestBody":{"$ref":"#/components/requestBodies/OverrideEndTime"},"responses":{"204":{"description":"Success."},"400":{"$ref":"#/components/responses/400badbody"},"403":{"$ref":"#/components/responses/403accesszoneoverride"}}}}}}
```

## Set access zone to code or card

> Sends an override to an access zone to change its mode to 'Code or Card - No PIN',\
> meaning you can use your user code or the zone's 'code-only code' to open its doors,\
> depending on the reader's configuration.  You will not need a PIN on a terminal.\
> \
> Take this URL from the \`commands\` block of an access zone.  In there is a block called\
> \`codeOnly\`, containing a field \`href\`.  That is the URL of this method.\
> \
> The URL from \`commands.codeOnlyPin.href\` (as opposed to \`codeOnly\` without the \`Pin\`) will send an override to an\
> access zone to change its mode to 'Code or Card - PIN', meaning you \_will\_ need a PIN on a terminal.\
> \
> If you do not give the override an end time in the body it will remain in place until the\
> next scheduled change.<br>

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"Access Zones","description":"These methods give you read access to Access Zones in the Command Centre database, and\nlet you change their modes, lock them down, and send other overrides.\n\nThe first use case below introduces the main entry point.  It is a paginated search interface\nthat gives any number of access zones, each containing the fields you ask for in the query.\n\n## Overrides\n\nNote:\n\n1. End-times on overrides are not accurate to the second.  Internally, Command Centre\n   converts the end time to a duration, so you may find that submitting end times in\n   the very near future does not have the exact effect you expect.\n2. An override without an end time lasts until the next\n   mode change or 'cancel untimed overrides' entry in the access zone's schedule.\n3. The end time you set for an override cannot be in the past or more than 24 hours into\n   the future.\n\n## Access Zone status flags\n\nIf the access zone is online, its `statusFlags` field may contain one or more of these flags:\n\n- `saltoOutputOnly` means the access zone would be considered unconfigured because it is\n  missing doors, and therefore offline, except that it has a Salto output number assigned to it.\n  That is a normal operational configuration.\n\n- `mobileZone` also means the access zone would be considered unconfigured (missing doors) and\n  therefore offline, except that a mobile reader is able to badge cardholders into it, making it\n  a perfectly useful access zone.  It will also have a `secure` flag.\n\n- `lockedDown` means only cardholders with the privilege to enter locked-down zones shall pass.\n  The zone will also be 'secure'.  When the lockdown override ends it will return to its\n  previous access mode.\n- `usePin` means when you use a card at a reader to unlock the door or at a terminal to control\n  an alarm zone, you will also need your PIN.\n- `zoneCountTooHigh` means the zone count is above its maximum.\n- `zoneCountTooLow` means the zone count is below its minimum.\n- `zoneCountInGrace` means the zone count recently became too low or high.\n\nThe following four give the zone's access state.  An online access zone will always return one\nof them.\n\n- `secure` means the doors are locked.\n- `dualAuth` means the doors are locked and - depending on configuration - cardholders will need\n  a second credential to open them.\n- `codeOrCard` means you can unlock a door either with a card, the zone's access code, or (if\n  suitably configured on the reader) a personal user code.  You will not see this flag if the\n  zone is locked down.\n- `free` means the zone's doors are unlocked.  You will not see this when the zone is locked down.\n\n### Access Zone flag rules\n\n- If and only if the zone is online and not locked down, there will be exactly one of 'secure',\n  'dualAuth', 'codeOrCard', or 'free'.\n\n- If and only if the zone is online and locked down, there will be exactly one of 'secure' or\n  'dualAuth'.\n\n- Because 'saltoOutputOnly' and 'mobileZone' are variations of the unconfigured offline\n  condition, 'saltoOutputOnly' will be alone and only 'secure' will accompany 'mobileZone'.\n\n- If a zone has both a Salto output number and mobile access, only 'saltoOutputOnly' will\n  appear.\n\n- If there is 'zoneCountInGrace' there will always be exactly one of 'zoneCountTooHigh' or\n  'zoneCountTooLow' (never both).\n\nUsing the first three rules above, your test for an access zone being in error is 'secure',\n'dualAuth', 'codeOrCard', 'free', 'saltoOutputOnly', and 'mobileZone' all missing.\n\n## Use cases\n\n### Searching for access zones by name\n 1. `GET /api`.\n 2. Follow the link at `features.accessZones.accessZones.href`\n    [↪](access-zones#get-api-access_zones), appending a search term such as `name=substring` to\n    filter the access zones, and `fields` to tell the server what to return about each.  The\n    next section covers those query parameters.\n 3. Process the results, following the `next` link until there isn't one.\n\n### Changing an access zone's access mode\n 1. Find the href for the access zone using the process above.\n 2. GET it.\n 3. Find the API URL you require in the `commands` structure of the results, such as `free` or\n    `securePin`, from [the detail](models#accesszonedetail).  Use the `until` variants if\n    you are specifying an end time.\n 4. POST to that URL.  Some require a JSON object (resetting the zone count, and all\n     those with `until` in their command block keys).  The others expect an empty body.\n\n### Finding an access zone's status\n1. Find the href for the access zone using the process above, and GET it.\n3. Take the `updates` [↪](access-zones#get-api-access_zones-id-updates) href from that page.  For a\n   version 8.00 server append the query parameter separator (`?` or `&`) then\n   `fields=defaults,zoneCount` if you need the zone count as well as the default status fields.\n   The zone count is included by default in 8.10 and later.\n4. GET it.\n5. Use the flag rules above to interpret the status flags you receive.\n5. Follow the `next` link to stay up to date.\n\n## Licensing\n\nAll the POSTs that override items require RESTOverrides.\n\nIf you have RESTOverrides but not RESTStatus in 8.60 or later, the GETs return enough\ninformation to let you find the item you want to override but they do not return its status.  In\n8.50 and older, the GET will fail without RESTStatus.\n\nThe RESTOverrides and RESTStatus licences do not overlap: to watch the status of an item as well\nas override it, you will need both.\n"}],"servers":[{"url":"https://127.0.0.1:8904"}],"security":[{"API_key":[]},{"basic":[]}],"components":{"securitySchemes":{"API_key":{"type":"apiKey","name":"Authorization","in":"header","description":"\nClients authenticate by including a pre-shared API key in the `Authorization` header of each\nrequest after an authorisation method of `GGL-API-KEY`:\n\n`Authorization: GGL-API-KEY C774-B01F-D695-AA4B-215F-A158-AC22-ADEB`\n\nFor a fuller description see [API authentication](api-authentication).\n"},"basic":{"type":"http","scheme":"basic","description":"This is HTTP Basic authentication using a blank username and the API key as the password.\n\nExample:  `Authorization: Basic OkM3NzQtQjAxRi1ENjk1LUFBNEItMjE1Ri1BMTU4LUFDMjItQURFQg==`\n\nThat example is equivalent to the example in the description of the api_Key method:\nprepending a colon to the API key beginning with `C774` then encoding it into Base64\nproduces the 56 characters beginning with `OkM3`.\n\nThe colon is a separator between a username, which is blank in our case, and the password,\nwhich is our API key.\n\nFor a fuller description see [API authentication](api-authentication)\n"}},"parameters":{"requested_by":{"name":"requested_by","in":"query","required":false,"schema":{"type":"string"},"description":"Attributes this override to the cardholder with this ID rather than the REST operator.\nPrivilege checks will use the operator as normal, but event monitors and reports will state\nthat the person responsible for the override was the attributed cardholder, not the REST\noperator.  The REST operator will appear in a special mention in the event's details.\n\nFirst available in 8.70.  Versions older than 8.70 will ignore the parameter, leaving the\noverride attributed to the REST operator.\n"}},"requestBodies":{"OverrideEndTime":{"description":"Put this in the body of override POSTs to set the time at which the override should cease.\nThe API will reject the override if the string is not empty and it cannot parse it into a\ndate-time, but it will treat the override as having no end time if you misspell 'endTime'\nor if you send a blank string.\n\nCommand Centre computes an override's duration to a whole number of minutes with a minimum\nof one.  That means that a timed override will always end at a multiple of sixty seconds\nfrom the time the hardware receives the override request, which means the override will end\nwithin thirty seconds of the time you supplied here.  In versions older than 8.80, the\ndiscrepancy may be up to a minute.\n\nCareful observation of overrides submitted from the Configuration client and from the API\nwill reveal that they use different rounding methods.  Be assured, both result in overrides\nending within a minute of the requested time.\n","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"endTime":{"type":"string","format":"date-time"}}}}}}},"responses":{"400badbody":{"description":"The server could not parse the POST parameters.  There could be a syntax error in your JSON.\n"},"403accesszoneoverride":{"description":"The site does not have the RESTOverrides licence (in which case the body of the result will\nsay so), or the operator does not have a privilege that allows overriding access zones (such\nas 'Override').\n"}}},"paths":{"/api/access_zones/{id}/code_only":{"post":{"tags":["Access Zones"],"summary":"Set access zone to code or card","description":"Sends an override to an access zone to change its mode to 'Code or Card - No PIN',\nmeaning you can use your user code or the zone's 'code-only code' to open its doors,\ndepending on the reader's configuration.  You will not need a PIN on a terminal.\n\nTake this URL from the `commands` block of an access zone.  In there is a block called\n`codeOnly`, containing a field `href`.  That is the URL of this method.\n\nThe URL from `commands.codeOnlyPin.href` (as opposed to `codeOnly` without the `Pin`) will send an override to an\naccess zone to change its mode to 'Code or Card - PIN', meaning you _will_ need a PIN on a terminal.\n\nIf you do not give the override an end time in the body it will remain in place until the\nnext scheduled change.\n","parameters":[{"name":"id","in":"path","description":"The ID of the access zone.","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/requested_by"}],"requestBody":{"$ref":"#/components/requestBodies/OverrideEndTime"},"responses":{"204":{"description":"Success."},"400":{"$ref":"#/components/responses/400badbody"},"403":{"$ref":"#/components/responses/403accesszoneoverride"}}}}}}
```

## Set access zone to dual auth

> Sends an override to an access zone to change its mode to 'dual auth - no PIN', meaning you\
> will need two badges to open its doors (either two different cardholders or two credentials\
> for the same cardholder, depending on the access zone's configuration), and they will not\
> need a PIN.  Terminal functions will require a card but no PIN.\
> \
> Take this URL from the \`commands\` block of an access zone.  In there is a block called\
> \`dualAuth\`, containing a field \`href\`.  That is the URL of this method.\
> \
> The URL from \`commands.dualAuthPin.href\` (as opposed to \`dualAuth\` without the \`Pin\`) will send an override to an\
> access zone to change its mode to 'dual auth - PIN', meaning you \_will\_ need a PIN on a terminal.\
> \
> If you do not give the override an end time in the body it will remain in place until the\
> next scheduled change.<br>

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"Access Zones","description":"These methods give you read access to Access Zones in the Command Centre database, and\nlet you change their modes, lock them down, and send other overrides.\n\nThe first use case below introduces the main entry point.  It is a paginated search interface\nthat gives any number of access zones, each containing the fields you ask for in the query.\n\n## Overrides\n\nNote:\n\n1. End-times on overrides are not accurate to the second.  Internally, Command Centre\n   converts the end time to a duration, so you may find that submitting end times in\n   the very near future does not have the exact effect you expect.\n2. An override without an end time lasts until the next\n   mode change or 'cancel untimed overrides' entry in the access zone's schedule.\n3. The end time you set for an override cannot be in the past or more than 24 hours into\n   the future.\n\n## Access Zone status flags\n\nIf the access zone is online, its `statusFlags` field may contain one or more of these flags:\n\n- `saltoOutputOnly` means the access zone would be considered unconfigured because it is\n  missing doors, and therefore offline, except that it has a Salto output number assigned to it.\n  That is a normal operational configuration.\n\n- `mobileZone` also means the access zone would be considered unconfigured (missing doors) and\n  therefore offline, except that a mobile reader is able to badge cardholders into it, making it\n  a perfectly useful access zone.  It will also have a `secure` flag.\n\n- `lockedDown` means only cardholders with the privilege to enter locked-down zones shall pass.\n  The zone will also be 'secure'.  When the lockdown override ends it will return to its\n  previous access mode.\n- `usePin` means when you use a card at a reader to unlock the door or at a terminal to control\n  an alarm zone, you will also need your PIN.\n- `zoneCountTooHigh` means the zone count is above its maximum.\n- `zoneCountTooLow` means the zone count is below its minimum.\n- `zoneCountInGrace` means the zone count recently became too low or high.\n\nThe following four give the zone's access state.  An online access zone will always return one\nof them.\n\n- `secure` means the doors are locked.\n- `dualAuth` means the doors are locked and - depending on configuration - cardholders will need\n  a second credential to open them.\n- `codeOrCard` means you can unlock a door either with a card, the zone's access code, or (if\n  suitably configured on the reader) a personal user code.  You will not see this flag if the\n  zone is locked down.\n- `free` means the zone's doors are unlocked.  You will not see this when the zone is locked down.\n\n### Access Zone flag rules\n\n- If and only if the zone is online and not locked down, there will be exactly one of 'secure',\n  'dualAuth', 'codeOrCard', or 'free'.\n\n- If and only if the zone is online and locked down, there will be exactly one of 'secure' or\n  'dualAuth'.\n\n- Because 'saltoOutputOnly' and 'mobileZone' are variations of the unconfigured offline\n  condition, 'saltoOutputOnly' will be alone and only 'secure' will accompany 'mobileZone'.\n\n- If a zone has both a Salto output number and mobile access, only 'saltoOutputOnly' will\n  appear.\n\n- If there is 'zoneCountInGrace' there will always be exactly one of 'zoneCountTooHigh' or\n  'zoneCountTooLow' (never both).\n\nUsing the first three rules above, your test for an access zone being in error is 'secure',\n'dualAuth', 'codeOrCard', 'free', 'saltoOutputOnly', and 'mobileZone' all missing.\n\n## Use cases\n\n### Searching for access zones by name\n 1. `GET /api`.\n 2. Follow the link at `features.accessZones.accessZones.href`\n    [↪](access-zones#get-api-access_zones), appending a search term such as `name=substring` to\n    filter the access zones, and `fields` to tell the server what to return about each.  The\n    next section covers those query parameters.\n 3. Process the results, following the `next` link until there isn't one.\n\n### Changing an access zone's access mode\n 1. Find the href for the access zone using the process above.\n 2. GET it.\n 3. Find the API URL you require in the `commands` structure of the results, such as `free` or\n    `securePin`, from [the detail](models#accesszonedetail).  Use the `until` variants if\n    you are specifying an end time.\n 4. POST to that URL.  Some require a JSON object (resetting the zone count, and all\n     those with `until` in their command block keys).  The others expect an empty body.\n\n### Finding an access zone's status\n1. Find the href for the access zone using the process above, and GET it.\n3. Take the `updates` [↪](access-zones#get-api-access_zones-id-updates) href from that page.  For a\n   version 8.00 server append the query parameter separator (`?` or `&`) then\n   `fields=defaults,zoneCount` if you need the zone count as well as the default status fields.\n   The zone count is included by default in 8.10 and later.\n4. GET it.\n5. Use the flag rules above to interpret the status flags you receive.\n5. Follow the `next` link to stay up to date.\n\n## Licensing\n\nAll the POSTs that override items require RESTOverrides.\n\nIf you have RESTOverrides but not RESTStatus in 8.60 or later, the GETs return enough\ninformation to let you find the item you want to override but they do not return its status.  In\n8.50 and older, the GET will fail without RESTStatus.\n\nThe RESTOverrides and RESTStatus licences do not overlap: to watch the status of an item as well\nas override it, you will need both.\n"}],"servers":[{"url":"https://127.0.0.1:8904"}],"security":[{"API_key":[]},{"basic":[]}],"components":{"securitySchemes":{"API_key":{"type":"apiKey","name":"Authorization","in":"header","description":"\nClients authenticate by including a pre-shared API key in the `Authorization` header of each\nrequest after an authorisation method of `GGL-API-KEY`:\n\n`Authorization: GGL-API-KEY C774-B01F-D695-AA4B-215F-A158-AC22-ADEB`\n\nFor a fuller description see [API authentication](api-authentication).\n"},"basic":{"type":"http","scheme":"basic","description":"This is HTTP Basic authentication using a blank username and the API key as the password.\n\nExample:  `Authorization: Basic OkM3NzQtQjAxRi1ENjk1LUFBNEItMjE1Ri1BMTU4LUFDMjItQURFQg==`\n\nThat example is equivalent to the example in the description of the api_Key method:\nprepending a colon to the API key beginning with `C774` then encoding it into Base64\nproduces the 56 characters beginning with `OkM3`.\n\nThe colon is a separator between a username, which is blank in our case, and the password,\nwhich is our API key.\n\nFor a fuller description see [API authentication](api-authentication)\n"}},"parameters":{"requested_by":{"name":"requested_by","in":"query","required":false,"schema":{"type":"string"},"description":"Attributes this override to the cardholder with this ID rather than the REST operator.\nPrivilege checks will use the operator as normal, but event monitors and reports will state\nthat the person responsible for the override was the attributed cardholder, not the REST\noperator.  The REST operator will appear in a special mention in the event's details.\n\nFirst available in 8.70.  Versions older than 8.70 will ignore the parameter, leaving the\noverride attributed to the REST operator.\n"}},"requestBodies":{"OverrideEndTime":{"description":"Put this in the body of override POSTs to set the time at which the override should cease.\nThe API will reject the override if the string is not empty and it cannot parse it into a\ndate-time, but it will treat the override as having no end time if you misspell 'endTime'\nor if you send a blank string.\n\nCommand Centre computes an override's duration to a whole number of minutes with a minimum\nof one.  That means that a timed override will always end at a multiple of sixty seconds\nfrom the time the hardware receives the override request, which means the override will end\nwithin thirty seconds of the time you supplied here.  In versions older than 8.80, the\ndiscrepancy may be up to a minute.\n\nCareful observation of overrides submitted from the Configuration client and from the API\nwill reveal that they use different rounding methods.  Be assured, both result in overrides\nending within a minute of the requested time.\n","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"endTime":{"type":"string","format":"date-time"}}}}}}},"responses":{"400badbody":{"description":"The server could not parse the POST parameters.  There could be a syntax error in your JSON.\n"},"403accesszoneoverride":{"description":"The site does not have the RESTOverrides licence (in which case the body of the result will\nsay so), or the operator does not have a privilege that allows overriding access zones (such\nas 'Override').\n"}}},"paths":{"/api/access_zones/{id}/dual_auth":{"post":{"tags":["Access Zones"],"summary":"Set access zone to dual auth","description":"Sends an override to an access zone to change its mode to 'dual auth - no PIN', meaning you\nwill need two badges to open its doors (either two different cardholders or two credentials\nfor the same cardholder, depending on the access zone's configuration), and they will not\nneed a PIN.  Terminal functions will require a card but no PIN.\n\nTake this URL from the `commands` block of an access zone.  In there is a block called\n`dualAuth`, containing a field `href`.  That is the URL of this method.\n\nThe URL from `commands.dualAuthPin.href` (as opposed to `dualAuth` without the `Pin`) will send an override to an\naccess zone to change its mode to 'dual auth - PIN', meaning you _will_ need a PIN on a terminal.\n\nIf you do not give the override an end time in the body it will remain in place until the\nnext scheduled change.\n","parameters":[{"name":"id","in":"path","description":"The ID of the access zone.","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/requested_by"}],"requestBody":{"$ref":"#/components/requestBodies/OverrideEndTime"},"responses":{"204":{"description":"Success."},"400":{"$ref":"#/components/responses/400badbody"},"403":{"$ref":"#/components/responses/403accesszoneoverride"}}}}}}
```

## Forgive anti-passback on a zone

> Sends an override to an access zone to forgive anti-passback for all cardholders in the zone.<br>

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"Access Zones","description":"These methods give you read access to Access Zones in the Command Centre database, and\nlet you change their modes, lock them down, and send other overrides.\n\nThe first use case below introduces the main entry point.  It is a paginated search interface\nthat gives any number of access zones, each containing the fields you ask for in the query.\n\n## Overrides\n\nNote:\n\n1. End-times on overrides are not accurate to the second.  Internally, Command Centre\n   converts the end time to a duration, so you may find that submitting end times in\n   the very near future does not have the exact effect you expect.\n2. An override without an end time lasts until the next\n   mode change or 'cancel untimed overrides' entry in the access zone's schedule.\n3. The end time you set for an override cannot be in the past or more than 24 hours into\n   the future.\n\n## Access Zone status flags\n\nIf the access zone is online, its `statusFlags` field may contain one or more of these flags:\n\n- `saltoOutputOnly` means the access zone would be considered unconfigured because it is\n  missing doors, and therefore offline, except that it has a Salto output number assigned to it.\n  That is a normal operational configuration.\n\n- `mobileZone` also means the access zone would be considered unconfigured (missing doors) and\n  therefore offline, except that a mobile reader is able to badge cardholders into it, making it\n  a perfectly useful access zone.  It will also have a `secure` flag.\n\n- `lockedDown` means only cardholders with the privilege to enter locked-down zones shall pass.\n  The zone will also be 'secure'.  When the lockdown override ends it will return to its\n  previous access mode.\n- `usePin` means when you use a card at a reader to unlock the door or at a terminal to control\n  an alarm zone, you will also need your PIN.\n- `zoneCountTooHigh` means the zone count is above its maximum.\n- `zoneCountTooLow` means the zone count is below its minimum.\n- `zoneCountInGrace` means the zone count recently became too low or high.\n\nThe following four give the zone's access state.  An online access zone will always return one\nof them.\n\n- `secure` means the doors are locked.\n- `dualAuth` means the doors are locked and - depending on configuration - cardholders will need\n  a second credential to open them.\n- `codeOrCard` means you can unlock a door either with a card, the zone's access code, or (if\n  suitably configured on the reader) a personal user code.  You will not see this flag if the\n  zone is locked down.\n- `free` means the zone's doors are unlocked.  You will not see this when the zone is locked down.\n\n### Access Zone flag rules\n\n- If and only if the zone is online and not locked down, there will be exactly one of 'secure',\n  'dualAuth', 'codeOrCard', or 'free'.\n\n- If and only if the zone is online and locked down, there will be exactly one of 'secure' or\n  'dualAuth'.\n\n- Because 'saltoOutputOnly' and 'mobileZone' are variations of the unconfigured offline\n  condition, 'saltoOutputOnly' will be alone and only 'secure' will accompany 'mobileZone'.\n\n- If a zone has both a Salto output number and mobile access, only 'saltoOutputOnly' will\n  appear.\n\n- If there is 'zoneCountInGrace' there will always be exactly one of 'zoneCountTooHigh' or\n  'zoneCountTooLow' (never both).\n\nUsing the first three rules above, your test for an access zone being in error is 'secure',\n'dualAuth', 'codeOrCard', 'free', 'saltoOutputOnly', and 'mobileZone' all missing.\n\n## Use cases\n\n### Searching for access zones by name\n 1. `GET /api`.\n 2. Follow the link at `features.accessZones.accessZones.href`\n    [↪](access-zones#get-api-access_zones), appending a search term such as `name=substring` to\n    filter the access zones, and `fields` to tell the server what to return about each.  The\n    next section covers those query parameters.\n 3. Process the results, following the `next` link until there isn't one.\n\n### Changing an access zone's access mode\n 1. Find the href for the access zone using the process above.\n 2. GET it.\n 3. Find the API URL you require in the `commands` structure of the results, such as `free` or\n    `securePin`, from [the detail](models#accesszonedetail).  Use the `until` variants if\n    you are specifying an end time.\n 4. POST to that URL.  Some require a JSON object (resetting the zone count, and all\n     those with `until` in their command block keys).  The others expect an empty body.\n\n### Finding an access zone's status\n1. Find the href for the access zone using the process above, and GET it.\n3. Take the `updates` [↪](access-zones#get-api-access_zones-id-updates) href from that page.  For a\n   version 8.00 server append the query parameter separator (`?` or `&`) then\n   `fields=defaults,zoneCount` if you need the zone count as well as the default status fields.\n   The zone count is included by default in 8.10 and later.\n4. GET it.\n5. Use the flag rules above to interpret the status flags you receive.\n5. Follow the `next` link to stay up to date.\n\n## Licensing\n\nAll the POSTs that override items require RESTOverrides.\n\nIf you have RESTOverrides but not RESTStatus in 8.60 or later, the GETs return enough\ninformation to let you find the item you want to override but they do not return its status.  In\n8.50 and older, the GET will fail without RESTStatus.\n\nThe RESTOverrides and RESTStatus licences do not overlap: to watch the status of an item as well\nas override it, you will need both.\n"}],"servers":[{"url":"https://127.0.0.1:8904"}],"security":[{"API_key":[]},{"basic":[]}],"components":{"securitySchemes":{"API_key":{"type":"apiKey","name":"Authorization","in":"header","description":"\nClients authenticate by including a pre-shared API key in the `Authorization` header of each\nrequest after an authorisation method of `GGL-API-KEY`:\n\n`Authorization: GGL-API-KEY C774-B01F-D695-AA4B-215F-A158-AC22-ADEB`\n\nFor a fuller description see [API authentication](api-authentication).\n"},"basic":{"type":"http","scheme":"basic","description":"This is HTTP Basic authentication using a blank username and the API key as the password.\n\nExample:  `Authorization: Basic OkM3NzQtQjAxRi1ENjk1LUFBNEItMjE1Ri1BMTU4LUFDMjItQURFQg==`\n\nThat example is equivalent to the example in the description of the api_Key method:\nprepending a colon to the API key beginning with `C774` then encoding it into Base64\nproduces the 56 characters beginning with `OkM3`.\n\nThe colon is a separator between a username, which is blank in our case, and the password,\nwhich is our API key.\n\nFor a fuller description see [API authentication](api-authentication)\n"}},"parameters":{"requested_by":{"name":"requested_by","in":"query","required":false,"schema":{"type":"string"},"description":"Attributes this override to the cardholder with this ID rather than the REST operator.\nPrivilege checks will use the operator as normal, but event monitors and reports will state\nthat the person responsible for the override was the attributed cardholder, not the REST\noperator.  The REST operator will appear in a special mention in the event's details.\n\nFirst available in 8.70.  Versions older than 8.70 will ignore the parameter, leaving the\noverride attributed to the REST operator.\n"}},"responses":{"403accesszoneoverride":{"description":"The site does not have the RESTOverrides licence (in which case the body of the result will\nsay so), or the operator does not have a privilege that allows overriding access zones (such\nas 'Override').\n"}}},"paths":{"/api/access_zones/{id}/forgive_anti_passback":{"post":{"tags":["Access Zones"],"summary":"Forgive anti-passback on a zone","description":"Sends an override to an access zone to forgive anti-passback for all cardholders in the zone.\n","parameters":[{"name":"id","in":"path","description":"The ID of the access zone.","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/requested_by"}],"responses":{"204":{"description":"Success."},"403":{"$ref":"#/components/responses/403accesszoneoverride"}}}}}}
```

## Lock a zone down

> Locks down an access zone.  In this mode, cardholders will need the 'Entry allowed during\
> lockdown' privilege to enter the zone, in addition to normal access.\
> \
> Take this URL from the \`commands\` block of an access zone.  In there is a block called\
> \`lockDown\`, containing a field \`href\`.  That is the URL of this method.\
> \
> It takes no parameters.  The lockdown will remain in place until cancelled, or the access\
> zone receives an override to another mode.<br>

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"Access Zones","description":"These methods give you read access to Access Zones in the Command Centre database, and\nlet you change their modes, lock them down, and send other overrides.\n\nThe first use case below introduces the main entry point.  It is a paginated search interface\nthat gives any number of access zones, each containing the fields you ask for in the query.\n\n## Overrides\n\nNote:\n\n1. End-times on overrides are not accurate to the second.  Internally, Command Centre\n   converts the end time to a duration, so you may find that submitting end times in\n   the very near future does not have the exact effect you expect.\n2. An override without an end time lasts until the next\n   mode change or 'cancel untimed overrides' entry in the access zone's schedule.\n3. The end time you set for an override cannot be in the past or more than 24 hours into\n   the future.\n\n## Access Zone status flags\n\nIf the access zone is online, its `statusFlags` field may contain one or more of these flags:\n\n- `saltoOutputOnly` means the access zone would be considered unconfigured because it is\n  missing doors, and therefore offline, except that it has a Salto output number assigned to it.\n  That is a normal operational configuration.\n\n- `mobileZone` also means the access zone would be considered unconfigured (missing doors) and\n  therefore offline, except that a mobile reader is able to badge cardholders into it, making it\n  a perfectly useful access zone.  It will also have a `secure` flag.\n\n- `lockedDown` means only cardholders with the privilege to enter locked-down zones shall pass.\n  The zone will also be 'secure'.  When the lockdown override ends it will return to its\n  previous access mode.\n- `usePin` means when you use a card at a reader to unlock the door or at a terminal to control\n  an alarm zone, you will also need your PIN.\n- `zoneCountTooHigh` means the zone count is above its maximum.\n- `zoneCountTooLow` means the zone count is below its minimum.\n- `zoneCountInGrace` means the zone count recently became too low or high.\n\nThe following four give the zone's access state.  An online access zone will always return one\nof them.\n\n- `secure` means the doors are locked.\n- `dualAuth` means the doors are locked and - depending on configuration - cardholders will need\n  a second credential to open them.\n- `codeOrCard` means you can unlock a door either with a card, the zone's access code, or (if\n  suitably configured on the reader) a personal user code.  You will not see this flag if the\n  zone is locked down.\n- `free` means the zone's doors are unlocked.  You will not see this when the zone is locked down.\n\n### Access Zone flag rules\n\n- If and only if the zone is online and not locked down, there will be exactly one of 'secure',\n  'dualAuth', 'codeOrCard', or 'free'.\n\n- If and only if the zone is online and locked down, there will be exactly one of 'secure' or\n  'dualAuth'.\n\n- Because 'saltoOutputOnly' and 'mobileZone' are variations of the unconfigured offline\n  condition, 'saltoOutputOnly' will be alone and only 'secure' will accompany 'mobileZone'.\n\n- If a zone has both a Salto output number and mobile access, only 'saltoOutputOnly' will\n  appear.\n\n- If there is 'zoneCountInGrace' there will always be exactly one of 'zoneCountTooHigh' or\n  'zoneCountTooLow' (never both).\n\nUsing the first three rules above, your test for an access zone being in error is 'secure',\n'dualAuth', 'codeOrCard', 'free', 'saltoOutputOnly', and 'mobileZone' all missing.\n\n## Use cases\n\n### Searching for access zones by name\n 1. `GET /api`.\n 2. Follow the link at `features.accessZones.accessZones.href`\n    [↪](access-zones#get-api-access_zones), appending a search term such as `name=substring` to\n    filter the access zones, and `fields` to tell the server what to return about each.  The\n    next section covers those query parameters.\n 3. Process the results, following the `next` link until there isn't one.\n\n### Changing an access zone's access mode\n 1. Find the href for the access zone using the process above.\n 2. GET it.\n 3. Find the API URL you require in the `commands` structure of the results, such as `free` or\n    `securePin`, from [the detail](models#accesszonedetail).  Use the `until` variants if\n    you are specifying an end time.\n 4. POST to that URL.  Some require a JSON object (resetting the zone count, and all\n     those with `until` in their command block keys).  The others expect an empty body.\n\n### Finding an access zone's status\n1. Find the href for the access zone using the process above, and GET it.\n3. Take the `updates` [↪](access-zones#get-api-access_zones-id-updates) href from that page.  For a\n   version 8.00 server append the query parameter separator (`?` or `&`) then\n   `fields=defaults,zoneCount` if you need the zone count as well as the default status fields.\n   The zone count is included by default in 8.10 and later.\n4. GET it.\n5. Use the flag rules above to interpret the status flags you receive.\n5. Follow the `next` link to stay up to date.\n\n## Licensing\n\nAll the POSTs that override items require RESTOverrides.\n\nIf you have RESTOverrides but not RESTStatus in 8.60 or later, the GETs return enough\ninformation to let you find the item you want to override but they do not return its status.  In\n8.50 and older, the GET will fail without RESTStatus.\n\nThe RESTOverrides and RESTStatus licences do not overlap: to watch the status of an item as well\nas override it, you will need both.\n"}],"servers":[{"url":"https://127.0.0.1:8904"}],"security":[{"API_key":[]},{"basic":[]}],"components":{"securitySchemes":{"API_key":{"type":"apiKey","name":"Authorization","in":"header","description":"\nClients authenticate by including a pre-shared API key in the `Authorization` header of each\nrequest after an authorisation method of `GGL-API-KEY`:\n\n`Authorization: GGL-API-KEY C774-B01F-D695-AA4B-215F-A158-AC22-ADEB`\n\nFor a fuller description see [API authentication](api-authentication).\n"},"basic":{"type":"http","scheme":"basic","description":"This is HTTP Basic authentication using a blank username and the API key as the password.\n\nExample:  `Authorization: Basic OkM3NzQtQjAxRi1ENjk1LUFBNEItMjE1Ri1BMTU4LUFDMjItQURFQg==`\n\nThat example is equivalent to the example in the description of the api_Key method:\nprepending a colon to the API key beginning with `C774` then encoding it into Base64\nproduces the 56 characters beginning with `OkM3`.\n\nThe colon is a separator between a username, which is blank in our case, and the password,\nwhich is our API key.\n\nFor a fuller description see [API authentication](api-authentication)\n"}},"parameters":{"requested_by":{"name":"requested_by","in":"query","required":false,"schema":{"type":"string"},"description":"Attributes this override to the cardholder with this ID rather than the REST operator.\nPrivilege checks will use the operator as normal, but event monitors and reports will state\nthat the person responsible for the override was the attributed cardholder, not the REST\noperator.  The REST operator will appear in a special mention in the event's details.\n\nFirst available in 8.70.  Versions older than 8.70 will ignore the parameter, leaving the\noverride attributed to the REST operator.\n"}},"responses":{"403accesszoneoverride":{"description":"The site does not have the RESTOverrides licence (in which case the body of the result will\nsay so), or the operator does not have a privilege that allows overriding access zones (such\nas 'Override').\n"}}},"paths":{"/api/access_zones/{id}/lock_down":{"post":{"tags":["Access Zones"],"summary":"Lock a zone down","description":"Locks down an access zone.  In this mode, cardholders will need the 'Entry allowed during\nlockdown' privilege to enter the zone, in addition to normal access.\n\nTake this URL from the `commands` block of an access zone.  In there is a block called\n`lockDown`, containing a field `href`.  That is the URL of this method.\n\nIt takes no parameters.  The lockdown will remain in place until cancelled, or the access\nzone receives an override to another mode.\n","parameters":[{"name":"id","in":"path","description":"The ID of the access zone.","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/requested_by"}],"responses":{"204":{"description":"Success."},"403":{"$ref":"#/components/responses/403accesszoneoverride"}}}}}}
```

## Cancel a zone lockdown

> Cancels a lockdown, returning it to its scheduled state.  It will not cancel any other kind\
> of override.\
> \
> Take this URL from the \`commands\` block of an access zone.  In there is a block called\
> \`cancelLockDown\`, containing a field \`href\`.  That is the URL of this method.<br>

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"Access Zones","description":"These methods give you read access to Access Zones in the Command Centre database, and\nlet you change their modes, lock them down, and send other overrides.\n\nThe first use case below introduces the main entry point.  It is a paginated search interface\nthat gives any number of access zones, each containing the fields you ask for in the query.\n\n## Overrides\n\nNote:\n\n1. End-times on overrides are not accurate to the second.  Internally, Command Centre\n   converts the end time to a duration, so you may find that submitting end times in\n   the very near future does not have the exact effect you expect.\n2. An override without an end time lasts until the next\n   mode change or 'cancel untimed overrides' entry in the access zone's schedule.\n3. The end time you set for an override cannot be in the past or more than 24 hours into\n   the future.\n\n## Access Zone status flags\n\nIf the access zone is online, its `statusFlags` field may contain one or more of these flags:\n\n- `saltoOutputOnly` means the access zone would be considered unconfigured because it is\n  missing doors, and therefore offline, except that it has a Salto output number assigned to it.\n  That is a normal operational configuration.\n\n- `mobileZone` also means the access zone would be considered unconfigured (missing doors) and\n  therefore offline, except that a mobile reader is able to badge cardholders into it, making it\n  a perfectly useful access zone.  It will also have a `secure` flag.\n\n- `lockedDown` means only cardholders with the privilege to enter locked-down zones shall pass.\n  The zone will also be 'secure'.  When the lockdown override ends it will return to its\n  previous access mode.\n- `usePin` means when you use a card at a reader to unlock the door or at a terminal to control\n  an alarm zone, you will also need your PIN.\n- `zoneCountTooHigh` means the zone count is above its maximum.\n- `zoneCountTooLow` means the zone count is below its minimum.\n- `zoneCountInGrace` means the zone count recently became too low or high.\n\nThe following four give the zone's access state.  An online access zone will always return one\nof them.\n\n- `secure` means the doors are locked.\n- `dualAuth` means the doors are locked and - depending on configuration - cardholders will need\n  a second credential to open them.\n- `codeOrCard` means you can unlock a door either with a card, the zone's access code, or (if\n  suitably configured on the reader) a personal user code.  You will not see this flag if the\n  zone is locked down.\n- `free` means the zone's doors are unlocked.  You will not see this when the zone is locked down.\n\n### Access Zone flag rules\n\n- If and only if the zone is online and not locked down, there will be exactly one of 'secure',\n  'dualAuth', 'codeOrCard', or 'free'.\n\n- If and only if the zone is online and locked down, there will be exactly one of 'secure' or\n  'dualAuth'.\n\n- Because 'saltoOutputOnly' and 'mobileZone' are variations of the unconfigured offline\n  condition, 'saltoOutputOnly' will be alone and only 'secure' will accompany 'mobileZone'.\n\n- If a zone has both a Salto output number and mobile access, only 'saltoOutputOnly' will\n  appear.\n\n- If there is 'zoneCountInGrace' there will always be exactly one of 'zoneCountTooHigh' or\n  'zoneCountTooLow' (never both).\n\nUsing the first three rules above, your test for an access zone being in error is 'secure',\n'dualAuth', 'codeOrCard', 'free', 'saltoOutputOnly', and 'mobileZone' all missing.\n\n## Use cases\n\n### Searching for access zones by name\n 1. `GET /api`.\n 2. Follow the link at `features.accessZones.accessZones.href`\n    [↪](access-zones#get-api-access_zones), appending a search term such as `name=substring` to\n    filter the access zones, and `fields` to tell the server what to return about each.  The\n    next section covers those query parameters.\n 3. Process the results, following the `next` link until there isn't one.\n\n### Changing an access zone's access mode\n 1. Find the href for the access zone using the process above.\n 2. GET it.\n 3. Find the API URL you require in the `commands` structure of the results, such as `free` or\n    `securePin`, from [the detail](models#accesszonedetail).  Use the `until` variants if\n    you are specifying an end time.\n 4. POST to that URL.  Some require a JSON object (resetting the zone count, and all\n     those with `until` in their command block keys).  The others expect an empty body.\n\n### Finding an access zone's status\n1. Find the href for the access zone using the process above, and GET it.\n3. Take the `updates` [↪](access-zones#get-api-access_zones-id-updates) href from that page.  For a\n   version 8.00 server append the query parameter separator (`?` or `&`) then\n   `fields=defaults,zoneCount` if you need the zone count as well as the default status fields.\n   The zone count is included by default in 8.10 and later.\n4. GET it.\n5. Use the flag rules above to interpret the status flags you receive.\n5. Follow the `next` link to stay up to date.\n\n## Licensing\n\nAll the POSTs that override items require RESTOverrides.\n\nIf you have RESTOverrides but not RESTStatus in 8.60 or later, the GETs return enough\ninformation to let you find the item you want to override but they do not return its status.  In\n8.50 and older, the GET will fail without RESTStatus.\n\nThe RESTOverrides and RESTStatus licences do not overlap: to watch the status of an item as well\nas override it, you will need both.\n"}],"servers":[{"url":"https://127.0.0.1:8904"}],"security":[{"API_key":[]},{"basic":[]}],"components":{"securitySchemes":{"API_key":{"type":"apiKey","name":"Authorization","in":"header","description":"\nClients authenticate by including a pre-shared API key in the `Authorization` header of each\nrequest after an authorisation method of `GGL-API-KEY`:\n\n`Authorization: GGL-API-KEY C774-B01F-D695-AA4B-215F-A158-AC22-ADEB`\n\nFor a fuller description see [API authentication](api-authentication).\n"},"basic":{"type":"http","scheme":"basic","description":"This is HTTP Basic authentication using a blank username and the API key as the password.\n\nExample:  `Authorization: Basic OkM3NzQtQjAxRi1ENjk1LUFBNEItMjE1Ri1BMTU4LUFDMjItQURFQg==`\n\nThat example is equivalent to the example in the description of the api_Key method:\nprepending a colon to the API key beginning with `C774` then encoding it into Base64\nproduces the 56 characters beginning with `OkM3`.\n\nThe colon is a separator between a username, which is blank in our case, and the password,\nwhich is our API key.\n\nFor a fuller description see [API authentication](api-authentication)\n"}},"parameters":{"requested_by":{"name":"requested_by","in":"query","required":false,"schema":{"type":"string"},"description":"Attributes this override to the cardholder with this ID rather than the REST operator.\nPrivilege checks will use the operator as normal, but event monitors and reports will state\nthat the person responsible for the override was the attributed cardholder, not the REST\noperator.  The REST operator will appear in a special mention in the event's details.\n\nFirst available in 8.70.  Versions older than 8.70 will ignore the parameter, leaving the\noverride attributed to the REST operator.\n"}},"responses":{"403accesszoneoverride":{"description":"The site does not have the RESTOverrides licence (in which case the body of the result will\nsay so), or the operator does not have a privilege that allows overriding access zones (such\nas 'Override').\n"}}},"paths":{"/api/access_zones/{id}/cancel_lock_down":{"post":{"tags":["Access Zones"],"summary":"Cancel a zone lockdown","description":"Cancels a lockdown, returning it to its scheduled state.  It will not cancel any other kind\nof override.\n\nTake this URL from the `commands` block of an access zone.  In there is a block called\n`cancelLockDown`, containing a field `href`.  That is the URL of this method.\n","parameters":[{"name":"id","in":"path","description":"The ID of the access zone.","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/requested_by"}],"responses":{"204":{"description":"Success."},"403":{"$ref":"#/components/responses/403accesszoneoverride"}}}}}}
```

## Set a zone count

> Sets the count of cardholders inside a zone.<br>

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"Access Zones","description":"These methods give you read access to Access Zones in the Command Centre database, and\nlet you change their modes, lock them down, and send other overrides.\n\nThe first use case below introduces the main entry point.  It is a paginated search interface\nthat gives any number of access zones, each containing the fields you ask for in the query.\n\n## Overrides\n\nNote:\n\n1. End-times on overrides are not accurate to the second.  Internally, Command Centre\n   converts the end time to a duration, so you may find that submitting end times in\n   the very near future does not have the exact effect you expect.\n2. An override without an end time lasts until the next\n   mode change or 'cancel untimed overrides' entry in the access zone's schedule.\n3. The end time you set for an override cannot be in the past or more than 24 hours into\n   the future.\n\n## Access Zone status flags\n\nIf the access zone is online, its `statusFlags` field may contain one or more of these flags:\n\n- `saltoOutputOnly` means the access zone would be considered unconfigured because it is\n  missing doors, and therefore offline, except that it has a Salto output number assigned to it.\n  That is a normal operational configuration.\n\n- `mobileZone` also means the access zone would be considered unconfigured (missing doors) and\n  therefore offline, except that a mobile reader is able to badge cardholders into it, making it\n  a perfectly useful access zone.  It will also have a `secure` flag.\n\n- `lockedDown` means only cardholders with the privilege to enter locked-down zones shall pass.\n  The zone will also be 'secure'.  When the lockdown override ends it will return to its\n  previous access mode.\n- `usePin` means when you use a card at a reader to unlock the door or at a terminal to control\n  an alarm zone, you will also need your PIN.\n- `zoneCountTooHigh` means the zone count is above its maximum.\n- `zoneCountTooLow` means the zone count is below its minimum.\n- `zoneCountInGrace` means the zone count recently became too low or high.\n\nThe following four give the zone's access state.  An online access zone will always return one\nof them.\n\n- `secure` means the doors are locked.\n- `dualAuth` means the doors are locked and - depending on configuration - cardholders will need\n  a second credential to open them.\n- `codeOrCard` means you can unlock a door either with a card, the zone's access code, or (if\n  suitably configured on the reader) a personal user code.  You will not see this flag if the\n  zone is locked down.\n- `free` means the zone's doors are unlocked.  You will not see this when the zone is locked down.\n\n### Access Zone flag rules\n\n- If and only if the zone is online and not locked down, there will be exactly one of 'secure',\n  'dualAuth', 'codeOrCard', or 'free'.\n\n- If and only if the zone is online and locked down, there will be exactly one of 'secure' or\n  'dualAuth'.\n\n- Because 'saltoOutputOnly' and 'mobileZone' are variations of the unconfigured offline\n  condition, 'saltoOutputOnly' will be alone and only 'secure' will accompany 'mobileZone'.\n\n- If a zone has both a Salto output number and mobile access, only 'saltoOutputOnly' will\n  appear.\n\n- If there is 'zoneCountInGrace' there will always be exactly one of 'zoneCountTooHigh' or\n  'zoneCountTooLow' (never both).\n\nUsing the first three rules above, your test for an access zone being in error is 'secure',\n'dualAuth', 'codeOrCard', 'free', 'saltoOutputOnly', and 'mobileZone' all missing.\n\n## Use cases\n\n### Searching for access zones by name\n 1. `GET /api`.\n 2. Follow the link at `features.accessZones.accessZones.href`\n    [↪](access-zones#get-api-access_zones), appending a search term such as `name=substring` to\n    filter the access zones, and `fields` to tell the server what to return about each.  The\n    next section covers those query parameters.\n 3. Process the results, following the `next` link until there isn't one.\n\n### Changing an access zone's access mode\n 1. Find the href for the access zone using the process above.\n 2. GET it.\n 3. Find the API URL you require in the `commands` structure of the results, such as `free` or\n    `securePin`, from [the detail](models#accesszonedetail).  Use the `until` variants if\n    you are specifying an end time.\n 4. POST to that URL.  Some require a JSON object (resetting the zone count, and all\n     those with `until` in their command block keys).  The others expect an empty body.\n\n### Finding an access zone's status\n1. Find the href for the access zone using the process above, and GET it.\n3. Take the `updates` [↪](access-zones#get-api-access_zones-id-updates) href from that page.  For a\n   version 8.00 server append the query parameter separator (`?` or `&`) then\n   `fields=defaults,zoneCount` if you need the zone count as well as the default status fields.\n   The zone count is included by default in 8.10 and later.\n4. GET it.\n5. Use the flag rules above to interpret the status flags you receive.\n5. Follow the `next` link to stay up to date.\n\n## Licensing\n\nAll the POSTs that override items require RESTOverrides.\n\nIf you have RESTOverrides but not RESTStatus in 8.60 or later, the GETs return enough\ninformation to let you find the item you want to override but they do not return its status.  In\n8.50 and older, the GET will fail without RESTStatus.\n\nThe RESTOverrides and RESTStatus licences do not overlap: to watch the status of an item as well\nas override it, you will need both.\n"}],"servers":[{"url":"https://127.0.0.1:8904"}],"security":[{"API_key":[]},{"basic":[]}],"components":{"securitySchemes":{"API_key":{"type":"apiKey","name":"Authorization","in":"header","description":"\nClients authenticate by including a pre-shared API key in the `Authorization` header of each\nrequest after an authorisation method of `GGL-API-KEY`:\n\n`Authorization: GGL-API-KEY C774-B01F-D695-AA4B-215F-A158-AC22-ADEB`\n\nFor a fuller description see [API authentication](api-authentication).\n"},"basic":{"type":"http","scheme":"basic","description":"This is HTTP Basic authentication using a blank username and the API key as the password.\n\nExample:  `Authorization: Basic OkM3NzQtQjAxRi1ENjk1LUFBNEItMjE1Ri1BMTU4LUFDMjItQURFQg==`\n\nThat example is equivalent to the example in the description of the api_Key method:\nprepending a colon to the API key beginning with `C774` then encoding it into Base64\nproduces the 56 characters beginning with `OkM3`.\n\nThe colon is a separator between a username, which is blank in our case, and the password,\nwhich is our API key.\n\nFor a fuller description see [API authentication](api-authentication)\n"}},"parameters":{"requested_by":{"name":"requested_by","in":"query","required":false,"schema":{"type":"string"},"description":"Attributes this override to the cardholder with this ID rather than the REST operator.\nPrivilege checks will use the operator as normal, but event monitors and reports will state\nthat the person responsible for the override was the attributed cardholder, not the REST\noperator.  The REST operator will appear in a special mention in the event's details.\n\nFirst available in 8.70.  Versions older than 8.70 will ignore the parameter, leaving the\noverride attributed to the REST operator.\n"}},"responses":{"400badbody":{"description":"The server could not parse the POST parameters.  There could be a syntax error in your JSON.\n"},"403accesszoneoverride":{"description":"The site does not have the RESTOverrides licence (in which case the body of the result will\nsay so), or the operator does not have a privilege that allows overriding access zones (such\nas 'Override').\n"}}},"paths":{"/api/access_zones/{id}/set_zone_count":{"post":{"tags":["Access Zones"],"summary":"Set a zone count","description":"Sets the count of cardholders inside a zone.\n","parameters":[{"name":"id","in":"path","description":"The ID of the access zone.","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/requested_by"}],"requestBody":{"description":"The new cardholder count for the zone.","content":{"application/json":{"schema":{"required":["zoneCount"],"type":"object","properties":{"zoneCount":{"type":"integer","description":"Put this in the body of access zone override POSTs to set the count of cardholders in the\naccess zone.\n"}}}}},"required":true},"responses":{"204":{"description":"Success."},"400":{"$ref":"#/components/responses/400badbody"},"403":{"$ref":"#/components/responses/403accesszoneoverride"}}}}}}
```

## Cancel mode override

> Cancels an override, returning the access zone to its scheduled state.\
> \
> Take this URL from the \`commands\` block of an access zone.  In there is a block called\
> \`cancel\`, containing a field \`href\`.  That is the URL of this method.\
> \
> This command will achieve nothing if the access zone is not controlled by a\
> schedule, because without a schedule the access zone does not have the concept of a\
> 'normal' state.\
> \
> It will not cancel a lockdown.  For that you need \`cancel\_lock\_down\`.<br>

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"Access Zones","description":"These methods give you read access to Access Zones in the Command Centre database, and\nlet you change their modes, lock them down, and send other overrides.\n\nThe first use case below introduces the main entry point.  It is a paginated search interface\nthat gives any number of access zones, each containing the fields you ask for in the query.\n\n## Overrides\n\nNote:\n\n1. End-times on overrides are not accurate to the second.  Internally, Command Centre\n   converts the end time to a duration, so you may find that submitting end times in\n   the very near future does not have the exact effect you expect.\n2. An override without an end time lasts until the next\n   mode change or 'cancel untimed overrides' entry in the access zone's schedule.\n3. The end time you set for an override cannot be in the past or more than 24 hours into\n   the future.\n\n## Access Zone status flags\n\nIf the access zone is online, its `statusFlags` field may contain one or more of these flags:\n\n- `saltoOutputOnly` means the access zone would be considered unconfigured because it is\n  missing doors, and therefore offline, except that it has a Salto output number assigned to it.\n  That is a normal operational configuration.\n\n- `mobileZone` also means the access zone would be considered unconfigured (missing doors) and\n  therefore offline, except that a mobile reader is able to badge cardholders into it, making it\n  a perfectly useful access zone.  It will also have a `secure` flag.\n\n- `lockedDown` means only cardholders with the privilege to enter locked-down zones shall pass.\n  The zone will also be 'secure'.  When the lockdown override ends it will return to its\n  previous access mode.\n- `usePin` means when you use a card at a reader to unlock the door or at a terminal to control\n  an alarm zone, you will also need your PIN.\n- `zoneCountTooHigh` means the zone count is above its maximum.\n- `zoneCountTooLow` means the zone count is below its minimum.\n- `zoneCountInGrace` means the zone count recently became too low or high.\n\nThe following four give the zone's access state.  An online access zone will always return one\nof them.\n\n- `secure` means the doors are locked.\n- `dualAuth` means the doors are locked and - depending on configuration - cardholders will need\n  a second credential to open them.\n- `codeOrCard` means you can unlock a door either with a card, the zone's access code, or (if\n  suitably configured on the reader) a personal user code.  You will not see this flag if the\n  zone is locked down.\n- `free` means the zone's doors are unlocked.  You will not see this when the zone is locked down.\n\n### Access Zone flag rules\n\n- If and only if the zone is online and not locked down, there will be exactly one of 'secure',\n  'dualAuth', 'codeOrCard', or 'free'.\n\n- If and only if the zone is online and locked down, there will be exactly one of 'secure' or\n  'dualAuth'.\n\n- Because 'saltoOutputOnly' and 'mobileZone' are variations of the unconfigured offline\n  condition, 'saltoOutputOnly' will be alone and only 'secure' will accompany 'mobileZone'.\n\n- If a zone has both a Salto output number and mobile access, only 'saltoOutputOnly' will\n  appear.\n\n- If there is 'zoneCountInGrace' there will always be exactly one of 'zoneCountTooHigh' or\n  'zoneCountTooLow' (never both).\n\nUsing the first three rules above, your test for an access zone being in error is 'secure',\n'dualAuth', 'codeOrCard', 'free', 'saltoOutputOnly', and 'mobileZone' all missing.\n\n## Use cases\n\n### Searching for access zones by name\n 1. `GET /api`.\n 2. Follow the link at `features.accessZones.accessZones.href`\n    [↪](access-zones#get-api-access_zones), appending a search term such as `name=substring` to\n    filter the access zones, and `fields` to tell the server what to return about each.  The\n    next section covers those query parameters.\n 3. Process the results, following the `next` link until there isn't one.\n\n### Changing an access zone's access mode\n 1. Find the href for the access zone using the process above.\n 2. GET it.\n 3. Find the API URL you require in the `commands` structure of the results, such as `free` or\n    `securePin`, from [the detail](models#accesszonedetail).  Use the `until` variants if\n    you are specifying an end time.\n 4. POST to that URL.  Some require a JSON object (resetting the zone count, and all\n     those with `until` in their command block keys).  The others expect an empty body.\n\n### Finding an access zone's status\n1. Find the href for the access zone using the process above, and GET it.\n3. Take the `updates` [↪](access-zones#get-api-access_zones-id-updates) href from that page.  For a\n   version 8.00 server append the query parameter separator (`?` or `&`) then\n   `fields=defaults,zoneCount` if you need the zone count as well as the default status fields.\n   The zone count is included by default in 8.10 and later.\n4. GET it.\n5. Use the flag rules above to interpret the status flags you receive.\n5. Follow the `next` link to stay up to date.\n\n## Licensing\n\nAll the POSTs that override items require RESTOverrides.\n\nIf you have RESTOverrides but not RESTStatus in 8.60 or later, the GETs return enough\ninformation to let you find the item you want to override but they do not return its status.  In\n8.50 and older, the GET will fail without RESTStatus.\n\nThe RESTOverrides and RESTStatus licences do not overlap: to watch the status of an item as well\nas override it, you will need both.\n"}],"servers":[{"url":"https://127.0.0.1:8904"}],"security":[{"API_key":[]},{"basic":[]}],"components":{"securitySchemes":{"API_key":{"type":"apiKey","name":"Authorization","in":"header","description":"\nClients authenticate by including a pre-shared API key in the `Authorization` header of each\nrequest after an authorisation method of `GGL-API-KEY`:\n\n`Authorization: GGL-API-KEY C774-B01F-D695-AA4B-215F-A158-AC22-ADEB`\n\nFor a fuller description see [API authentication](api-authentication).\n"},"basic":{"type":"http","scheme":"basic","description":"This is HTTP Basic authentication using a blank username and the API key as the password.\n\nExample:  `Authorization: Basic OkM3NzQtQjAxRi1ENjk1LUFBNEItMjE1Ri1BMTU4LUFDMjItQURFQg==`\n\nThat example is equivalent to the example in the description of the api_Key method:\nprepending a colon to the API key beginning with `C774` then encoding it into Base64\nproduces the 56 characters beginning with `OkM3`.\n\nThe colon is a separator between a username, which is blank in our case, and the password,\nwhich is our API key.\n\nFor a fuller description see [API authentication](api-authentication)\n"}},"parameters":{"requested_by":{"name":"requested_by","in":"query","required":false,"schema":{"type":"string"},"description":"Attributes this override to the cardholder with this ID rather than the REST operator.\nPrivilege checks will use the operator as normal, but event monitors and reports will state\nthat the person responsible for the override was the attributed cardholder, not the REST\noperator.  The REST operator will appear in a special mention in the event's details.\n\nFirst available in 8.70.  Versions older than 8.70 will ignore the parameter, leaving the\noverride attributed to the REST operator.\n"}},"responses":{"403accesszoneoverride":{"description":"The site does not have the RESTOverrides licence (in which case the body of the result will\nsay so), or the operator does not have a privilege that allows overriding access zones (such\nas 'Override').\n"}}},"paths":{"/api/access_zones/{id}/cancel":{"post":{"tags":["Access Zones"],"summary":"Cancel mode override","description":"Cancels an override, returning the access zone to its scheduled state.\n\nTake this URL from the `commands` block of an access zone.  In there is a block called\n`cancel`, containing a field `href`.  That is the URL of this method.\n\nThis command will achieve nothing if the access zone is not controlled by a\nschedule, because without a schedule the access zone does not have the concept of a\n'normal' state.\n\nIt will not cancel a lockdown.  For that you need `cancel_lock_down`.\n","parameters":[{"name":"id","in":"path","description":"The ID of the access zone.","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/requested_by"}],"responses":{"204":{"description":"Success."},"403":{"$ref":"#/components/responses/403accesszoneoverride"}}}}}}
```

## Monitor an access zone

> See the \[item status topic]\(item-status) for how to use the updates APIs.\
> \
> Note that this API call is good for watching one item only; if you want to monitor several,\
> you are better off with a \[status subscription]\(items#status-subscriptions).\
> \
> Follow the 'updates' field in an access zone \[summary]\(models#accesszonesummary) or\
> \[details]\(models#accesszonedetail) page to get here rather than \[building it\
> yourself]\(forward-compatibility-hateoas).<br>

```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"Access Zones","description":"These methods give you read access to Access Zones in the Command Centre database, and\nlet you change their modes, lock them down, and send other overrides.\n\nThe first use case below introduces the main entry point.  It is a paginated search interface\nthat gives any number of access zones, each containing the fields you ask for in the query.\n\n## Overrides\n\nNote:\n\n1. End-times on overrides are not accurate to the second.  Internally, Command Centre\n   converts the end time to a duration, so you may find that submitting end times in\n   the very near future does not have the exact effect you expect.\n2. An override without an end time lasts until the next\n   mode change or 'cancel untimed overrides' entry in the access zone's schedule.\n3. The end time you set for an override cannot be in the past or more than 24 hours into\n   the future.\n\n## Access Zone status flags\n\nIf the access zone is online, its `statusFlags` field may contain one or more of these flags:\n\n- `saltoOutputOnly` means the access zone would be considered unconfigured because it is\n  missing doors, and therefore offline, except that it has a Salto output number assigned to it.\n  That is a normal operational configuration.\n\n- `mobileZone` also means the access zone would be considered unconfigured (missing doors) and\n  therefore offline, except that a mobile reader is able to badge cardholders into it, making it\n  a perfectly useful access zone.  It will also have a `secure` flag.\n\n- `lockedDown` means only cardholders with the privilege to enter locked-down zones shall pass.\n  The zone will also be 'secure'.  When the lockdown override ends it will return to its\n  previous access mode.\n- `usePin` means when you use a card at a reader to unlock the door or at a terminal to control\n  an alarm zone, you will also need your PIN.\n- `zoneCountTooHigh` means the zone count is above its maximum.\n- `zoneCountTooLow` means the zone count is below its minimum.\n- `zoneCountInGrace` means the zone count recently became too low or high.\n\nThe following four give the zone's access state.  An online access zone will always return one\nof them.\n\n- `secure` means the doors are locked.\n- `dualAuth` means the doors are locked and - depending on configuration - cardholders will need\n  a second credential to open them.\n- `codeOrCard` means you can unlock a door either with a card, the zone's access code, or (if\n  suitably configured on the reader) a personal user code.  You will not see this flag if the\n  zone is locked down.\n- `free` means the zone's doors are unlocked.  You will not see this when the zone is locked down.\n\n### Access Zone flag rules\n\n- If and only if the zone is online and not locked down, there will be exactly one of 'secure',\n  'dualAuth', 'codeOrCard', or 'free'.\n\n- If and only if the zone is online and locked down, there will be exactly one of 'secure' or\n  'dualAuth'.\n\n- Because 'saltoOutputOnly' and 'mobileZone' are variations of the unconfigured offline\n  condition, 'saltoOutputOnly' will be alone and only 'secure' will accompany 'mobileZone'.\n\n- If a zone has both a Salto output number and mobile access, only 'saltoOutputOnly' will\n  appear.\n\n- If there is 'zoneCountInGrace' there will always be exactly one of 'zoneCountTooHigh' or\n  'zoneCountTooLow' (never both).\n\nUsing the first three rules above, your test for an access zone being in error is 'secure',\n'dualAuth', 'codeOrCard', 'free', 'saltoOutputOnly', and 'mobileZone' all missing.\n\n## Use cases\n\n### Searching for access zones by name\n 1. `GET /api`.\n 2. Follow the link at `features.accessZones.accessZones.href`\n    [↪](access-zones#get-api-access_zones), appending a search term such as `name=substring` to\n    filter the access zones, and `fields` to tell the server what to return about each.  The\n    next section covers those query parameters.\n 3. Process the results, following the `next` link until there isn't one.\n\n### Changing an access zone's access mode\n 1. Find the href for the access zone using the process above.\n 2. GET it.\n 3. Find the API URL you require in the `commands` structure of the results, such as `free` or\n    `securePin`, from [the detail](models#accesszonedetail).  Use the `until` variants if\n    you are specifying an end time.\n 4. POST to that URL.  Some require a JSON object (resetting the zone count, and all\n     those with `until` in their command block keys).  The others expect an empty body.\n\n### Finding an access zone's status\n1. Find the href for the access zone using the process above, and GET it.\n3. Take the `updates` [↪](access-zones#get-api-access_zones-id-updates) href from that page.  For a\n   version 8.00 server append the query parameter separator (`?` or `&`) then\n   `fields=defaults,zoneCount` if you need the zone count as well as the default status fields.\n   The zone count is included by default in 8.10 and later.\n4. GET it.\n5. Use the flag rules above to interpret the status flags you receive.\n5. Follow the `next` link to stay up to date.\n\n## Licensing\n\nAll the POSTs that override items require RESTOverrides.\n\nIf you have RESTOverrides but not RESTStatus in 8.60 or later, the GETs return enough\ninformation to let you find the item you want to override but they do not return its status.  In\n8.50 and older, the GET will fail without RESTStatus.\n\nThe RESTOverrides and RESTStatus licences do not overlap: to watch the status of an item as well\nas override it, you will need both.\n"}],"servers":[{"url":"https://127.0.0.1:8904"}],"security":[{"API_key":[]},{"basic":[]}],"components":{"securitySchemes":{"API_key":{"type":"apiKey","name":"Authorization","in":"header","description":"\nClients authenticate by including a pre-shared API key in the `Authorization` header of each\nrequest after an authorisation method of `GGL-API-KEY`:\n\n`Authorization: GGL-API-KEY C774-B01F-D695-AA4B-215F-A158-AC22-ADEB`\n\nFor a fuller description see [API authentication](api-authentication).\n"},"basic":{"type":"http","scheme":"basic","description":"This is HTTP Basic authentication using a blank username and the API key as the password.\n\nExample:  `Authorization: Basic OkM3NzQtQjAxRi1ENjk1LUFBNEItMjE1Ri1BMTU4LUFDMjItQURFQg==`\n\nThat example is equivalent to the example in the description of the api_Key method:\nprepending a colon to the API key beginning with `C774` then encoding it into Base64\nproduces the 56 characters beginning with `OkM3`.\n\nThe colon is a separator between a username, which is blank in our case, and the password,\nwhich is our API key.\n\nFor a fuller description see [API authentication](api-authentication)\n"}},"responses":{"403nolicence":{"description":"A server running 8.50 or earlier is missing the RESTStatus licence.  A server running 8.60\nor later is missing both the RESTStatus and RESTOverrides licences.  One of those is enough\nfor this API call in 8.60 and later.\n"},"404accesszone":{"description":"The request's URL does not represent an access zone, or the operator does not have a privilege\non the zone's division that allows viewing access zones, such as 'View Site', 'Edit Site', or\n'Override'.\n"}}},"paths":{"/api/access_zones/{id}/updates":{"get":{"tags":["Access Zones"],"summary":"Monitor an access zone","description":"See the [item status topic](item-status) for how to use the updates APIs.\n\nNote that this API call is good for watching one item only; if you want to monitor several,\nyou are better off with a [status subscription](items#status-subscriptions).\n\nFollow the 'updates' field in an access zone [summary](models#accesszonesummary) or\n[details](models#accesszonedetail) page to get here rather than [building it\nyourself](forward-compatibility-hateoas).\n","parameters":[{"name":"id","in":"path","description":"The ID of the access zone.","required":true,"schema":{"type":"string"}},{"name":"fields","in":"query","explode":false,"description":"This instructs the server to return these fields in the update, instead of the default set.  Note that removing fields also\nsaves you from updates to those fields.\n","schema":{"type":"string","enum":["status","statusText","statusFlags","zoneCount"]}}],"responses":{"200":{"description":"Success.  The [introduction](access-zones) describes the three status fields and\nthe [access zone detail](models#accesszonedetail) describes `zoneCount`.\n","content":{"application/json":{"schema":{"type":"object"}}}},"403":{"$ref":"#/components/responses/403nolicence"},"404":{"$ref":"#/components/responses/404accesszone"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.security.gallagher.com/knowledge-hub/developer/rest-api/access-zones.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.