MagicDoorAPI
SupportOpen MagicDoor
API keys

Create an API key

Issues a new API key that acts as the calling user, and returns the secret in the response. This is the only time the secret is ever sent — MagicDoor stores a hash of it and nothing else. Requires the api_keys:write permission.

POST
https://auth.magicdoor.com/company-portal/api-keys

Authorization

Authorizationstringrequired
Bearer token — Send your API token in the Authorization header as Bearer <token>. Requests without a valid token are rejected with 401 Unauthorized.

Body

application/json

namestringrequired

How the key is labelled in MagicDoor, 1 to 100 characters. It is only used for telling keys apart later, so make it say what uses the key.

example: Nightly rent-roll sync
permissionsstring[]

What the key may do, as resource:action strings, and at least one entry when present. Every entry must be something the calling user already holds. Leave the whole field out to issue an unscoped key that does whatever the calling user can do, re-read on every exchange, including permissions granted later.

example: ["properties:read","units:read","leases:read"]
expiresstring · date-time

When the key should stop working, given in the company's timezone and with no offset. Leave it out for a key that does not expire on its own.

example: 2027-01-01T00:00:00

Response

200 · The new key, secret included

apiKeyobject

The stored record for the new key.

keystring

The credential the integration stores and sends to the token endpoint. It appears here and in no other response, ever.

400 · The body failed validation — for example a name outside 1 to 100 characters, or an empty `permissions` array

401 · The access token is missing, expired, or invalid

403 · The caller does not hold `api_keys:write`, or asked for a permission they do not hold themselves, or is being shadowed by MagicDoor support

The secret is in this response and nowhere else

key is returned once, here. No endpoint returns it again, and MagicDoor cannot re-send it because only a hash is stored. Store it before you discard the response, or issue a replacement key.

What the key is allowed to do

A key always acts as the person who created it and can never do more than that person can. Sending an explicit permissions list freezes the key at that set; leaving it out gives an unscoped key that follows its user, widening as well as narrowing.

Either way the set is narrowed again to the user's current permissions on every exchange, so reducing a person reduces every key they issued. Only the name of an existing key can be changed — changing scope or expiry means issuing a new key and revoking the old one. Use List permissions to see the values permissions accepts.

Not while support is shadowing you

If a MagicDoor support agent is acting as you, this call returns 403 with the detail API keys cannot be created while shadowing a user. Otherwise the session would leave behind a credential that outlives it and looks exactly like one you made yourself.