---
updatedAt: 2025-08-18T14:36:16.000Z
agentTools:
  projectIndex: https://docs.keycafe.com/llms.txt
---

# Create Permission

Create a permission with a POST request to the endpoint.

Before granting a permission, the user must first be added as a member of the organization.\
If you need to add a SmartBox user to your organization, refer to the [Organization Membership API](https://docs.keycafe.com/reference/create-organization-membership).
For details on different user types, please see the [Help Center](https://support.keycafe.com/hc/en-us/articles/4410132828436-Adding-and-Managing-Users#h_01G28JQ8PNWTX7HNFEC2HCGYTE).

## Request Structure

The POST body must include the necessary data to create the permission, formatted as a JSON object.

```json
{
    "user": {
        "id": 123456
    },
    "key": {
        "id": 654321
    },
    "role": "ADMINISTRATOR"
}
```

<Callout icon="❗️" theme="error">
  Only one of the following should be specified in the request body:

  * Group ID
  * Key ID
  * Location ID\
    depending on the resource you are granting permission for.
</Callout>

## Response

If the request is successful, the API returns the newly created Permission object.

# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "Keycafe API",
    "version": "0"
  },
  "x-explorer-enabled": true,
  "x-proxy-enabled": true,
  "x-samples-languages": [
    "shell",
    "python",
    "go"
  ],
  "servers": [
    {
      "url": "https://www.keycafe.com/"
    }
  ],
  "components": {
    "securitySchemes": {
      "BasicAuth": {
        "type": "http",
        "scheme": "basic"
      }
    }
  },
  "security": [
    {
      "BasicAuth": []
    }
  ],
  "paths": {
    "/v0/permission": {
      "post": {
        "tags": [
          "Permission"
        ],
        "summary": "Create Permission",
        "description": "Create a permission with a POST request to the endpoint.",
        "operationId": "create-permission",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "role",
                  "user"
                ],
                "properties": {
                  "role": {
                    "type": "string",
                    "description": "The permission role: RESERVATION_ACCESS, EXCHANGE_ONLY, ADMINISTRATOR, VIEW_ONLY (deprecated).",
                    "enum": [
                      "EXCHANGE_ONLY",
                      "ADMINISTRATOR",
                      "RESERVATION_ACCESS",
                      "VIEW_ONLY"
                    ]
                  },
                  "user": {
                    "type": "object",
                    "description": "The user to grant the permission to.",
                    "properties": {
                      "id": {
                        "type": "integer",
                        "format": "int64"
                      }
                    }
                  },
                  "key": {
                    "type": "object",
                    "description": "The key the permission grants access to.",
                    "properties": {
                      "id": {
                        "type": "integer",
                        "format": "int64"
                      }
                    }
                  },
                  "location": {
                    "type": "object",
                    "description": "The location the permission grants access to.",
                    "properties": {
                      "id": {
                        "type": "integer",
                        "format": "int64"
                      }
                    }
                  },
                  "group": {
                    "type": "object",
                    "description": "The group the permission grants access to.",
                    "properties": {
                      "id": {
                        "type": "integer",
                        "description": "The unique identifier of the group.",
                        "format": "int64"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Permission granted to the user successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "integer",
                      "description": "Unique identifier of the permission record.",
                      "example": 123456
                    },
                    "role": {
                      "type": "string",
                      "description": "Role assigned to the user (e.g., ADMINISTRATOR, VIEWER).",
                      "example": "ADMINISTRATOR"
                    },
                    "user": {
                      "type": "object",
                      "description": "User who received the permission.",
                      "properties": {
                        "id": {
                          "type": "integer",
                          "description": "Unique identifier of the user.",
                          "example": 654321
                        },
                        "firstName": {
                          "type": "string",
                          "description": "First name of the user.",
                          "example": "Bob"
                        },
                        "lastName": {
                          "type": "string",
                          "description": "Last name of the user.",
                          "example": "Smith"
                        },
                        "type": {
                          "type": "string",
                          "description": "User type (e.g., FULL, SMARTBOX).",
                          "example": "FULL"
                        },
                        "email": {
                          "type": "string",
                          "format": "email",
                          "description": "Email address of the user.",
                          "example": "user@yourdomain.com"
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "Result": {
                    "value": "{\n    \"id\": 123456,\n    \"role\": \"ADMINISTRATOR\",\n    \"user\": {\n        \"firstName\": \"Bob\",\n        \"lastName\": \"Smith\",\n        \"id\": 654321,\n        \"type\": \"FULL\",\n        \"email\": \"user@yourdomain.com\"\n    }\n}"
                  }
                }
              }
            }
          },
          "400": {
            "description": "400",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          }
        },
        "deprecated": false,
        "parameters": []
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```