# /accesskeys/add

<img src="/files/-M5VUbC0pXukjxeyjAz2" alt="" data-size="line"> **`https://api.intserv.se/v1/accesskeys/add`**

Adds a new or updates an existing access key.

> Authentication Type: Integration API Key

### :envelope\_with\_arrow: Request Body Parameters

| Field             | Type                 | Description                                                                                                                                                                                                                                                                                                                          |
| ----------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`              | string(uuid)         | Identifier of the access key, if the intention is to update an existing one. Must be omitted if a new access key should be created.                                                                                                                                                                                                  |
| `key`             | AccessKey            | Access key specification. Must be specified if a new access key should be created. For updates the access key specification is used to identify the access key, but only if the `id` field has been omitted. For more information about how access key are specified, read the [Access Keys](/api-overview/access-keys.md) overview. |
| `pin`             | string(4)            | *(optional)* 4-digit PIN.                                                                                                                                                                                                                                                                                                            |
| `valid_from_date` | string               | *(optional)* Time when the access key becomes valid. If omitted, the access key becomes valid right away.                                                                                                                                                                                                                            |
| `valid_to_date`   | string               | *(optional)* Time when the access key expires. If omitted, the access key will never expire.                                                                                                                                                                                                                                         |
| `access_levels`   | array\[string(uuid)] | *(optional)* A list of one or more access level identifiers that represent the access levels that should be assigned to the access key. Access levels can be fetched from the [/accesslevels/get\_levels](/api-endpoints/accesslevels-list.md) endpoint.                                                                             |
| `person`          | Person               | *(optional)* Specifies details about the person a new access key should be assigned to. If omitted, an person will be automatically created. This field is not used when updating an existing access key.                                                                                                                            |

### Responses

#### :white\_check\_mark: 200 OK Response Body Parameters

{% tabs %}
{% tab title="Sample Response" %}

```
{
    "id": "d698c2a4-9aae-470d-bc85-727a70cf8838",
    "key": 
    {
        "identification": "0001234567890",
        "type": "proximity",
    },
    "valid_from_date": "2020-09-01T00:00:00Z",
    "valid_to_date": "2020-10-01T14:00:00Z",
    "access_levels": 
    [
        "ce8e881e-1392-4f53-b7c2-35eeb3ecaf3b"
    ],
    "person": 
    {
        "id": "14f47083-3b38-4c80-bbcf-9404bd4c08c7",
        "first_name": "xk561bv",
        "last_name:" "s2mp6z"
    }
}
```

{% endtab %}

{% tab title="Model Schema" %}

```
AddAccessKeyResponse {
    id (string(uuid)),
    key (AccessKey),
    valid_from_date (string),
    valid_to_date (string),
    access_levels (array[string(uuid)]),
    person (Person)
}
```

{% endtab %}
{% endtabs %}

### Models

#### AccessKey Model

| Field            | Type   | Description                                                                                            |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------ |
| `identification` | string | Identification number. Read the [Access Keys](/api-overview/access-keys.md) overview for more details. |
| `type`           | string | Type of access key. Can be either `proximity` or `code`.                                               |

#### Person Model

| Field        | Type         | Description                                                                                                                            |
| ------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `id`         | string(uuid) | Identifier of an existing person to assign the access key to.                                                                          |
| `first_name` | string(32)   | *(optional)* The persons first name. If not specified, a name will be automatically generated. Only used when a new person is created. |
| `last_name`  | string(32)   | *(optional)* The persons last name. If not specified, a name will be automatically generated. Only used when a new person is created.  |

### Examples

Sample payload to create a new access key assigned to a new person:

```
{
    "key": 
    {
        "identification": "0x00499602d2",
        "type": "proximity"
    },
    "pin": "1234",
    "valid_from_date": "2020-09-01T00:00:00Z",
    "valid_to_date": "2020-10-01T14:00:00Z",
    "access_levels":
    [
        "ce8e881e-1392-4f53-b7c2-35eeb3ecaf3b"
    ],
    "person": 
    {
        "first_name": "firstname",
        "last_name": "lastname"
    }
}
```

Sample payload to update an existing access key by id:

```
{
    "id": "ae40a59c-8d52-4f2f-bb01-efa30325882c",
    "pin": null,
    "valid_from_date": "2020-11-01T00:00:00Z",
    "valid_to_date": "2020-12-01T14:00:00Z",
    "access_levels":
    [
        "a5129f41-ed44-4f3b-95a2-bec53dd3e1e3"
    ]
}
```


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://apidocs.intserv.se/api-endpoints/accesskeys-add.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.