{"openapi":"3.1.0","info":{"title":"API Key","version":"1.0.0"},"paths":{"/api-keys":{"post":{"operationId":"authentication_getApiKey","summary":"Get API Key","description":"Obtain an API key using Basic Authentication. This key will be used for all other API requests.\n\nFor a user belonging to multiple companies, pass `company_id` to select which company the new key\nbelongs to. If omitted, the company is chosen deterministically: the user's first non-collaborator\ncompany, or otherwise their first company.\n\nUsers with a Viewer (view-only) seat in the selected company cannot create API keys and get a `403`.\n\nYour company ID can be found in the URL after logging in to the Coperniq UI: `https://app.coperniq.io/{company_id}/inbox`.\n","tags":["authentication"],"parameters":[{"name":"company_id","in":"query","description":"ID of the company the new API key should belong to. Required only when the authenticated user belongs to more than one company and the default (first non-collaborator company) is not the desired one. The user must belong to the given company.\nYour company ID can be found in the URL after logging in to the Coperniq UI: `https://app.coperniq.io/{company_id}/inbox`.\n","required":false,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"API key generated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyResponse"}}}},"400":{"description":"company_id was malformed (not a positive integer)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetApiKeyRequestBadRequestError"}}}},"401":{"description":"Authentication credentials are missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetApiKeyRequestUnauthorizedError"}}}},"403":{"description":"User does not have access to the requested company, or has a Viewer (view-only) seat in it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetApiKeyRequestForbiddenError"}}}}},"security":[{"BasicAuth":[]}]},"get":{"operationId":"apiKeyManagement_listApiKeys","summary":"List API Keys","description":"List the API keys in your company. Superadmins only.\n\nThe key values are never returned. Each key's `id` is a non-secret fingerprint; use it to delete the key with `DELETE /api-keys/{key_id}`, and use `keyPreview` (the key's last 4 characters) to recognize it.\n\nAuthenticate with Basic Auth (your Coperniq email and password), not an API key.\n","tags":["apiKeyManagement"],"parameters":[{"name":"company_id","in":"query","description":"ID of the company to manage. Needed only when the authenticated user belongs to more than one company and the default (their first non-collaborator company) is not the one you want. You must be a superadmin in that company.\nYour company ID can be found in the URL after logging in to the Coperniq UI: `https://app.coperniq.io/{company_id}/inbox`.\n","required":false,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"The company's API keys","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}}}}},"400":{"description":"Missing or malformed credentials, or `company_id` is not a positive integer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageResponse"}}}},"401":{"description":"Authentication credentials are missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListApiKeysRequestUnauthorizedError"}}}},"403":{"description":"The authenticated user is not a superadmin in the company, or doesn't belong to the requested `company_id`\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageResponse"}}}}},"security":[{"BasicAuth":[]}]}},"/api-users":{"get":{"operationId":"apiKeyManagement_listApiUsers","summary":"List API Users","description":"List the API users in your company. Superadmins only. An API user is the service account that API keys are issued to; each key's `userId` points to one.\n\nAuthenticate with Basic Auth (your Coperniq email and password), not an API key.\n","tags":["apiKeyManagement"],"parameters":[{"name":"company_id","in":"query","description":"ID of the company to manage. Needed only when the authenticated user belongs to more than one company and the default (their first non-collaborator company) is not the one you want. You must be a superadmin in that company.\nYour company ID can be found in the URL after logging in to the Coperniq UI: `https://app.coperniq.io/{company_id}/inbox`.\n","required":false,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"The company's API users","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ApiUser"}}}}},"400":{"description":"Missing or malformed credentials, or `company_id` is not a positive integer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageResponse"}}}},"401":{"description":"Authentication credentials are missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListApiUsersRequestUnauthorizedError"}}}},"403":{"description":"The authenticated user is not a superadmin in the company, or doesn't belong to the requested `company_id`\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageResponse"}}}}},"security":[{"BasicAuth":[]}]}},"/api-users/{user_id}/archive":{"post":{"operationId":"apiKeyManagement_archiveApiUser","summary":"Archive API User","description":"Archive an API user. Superadmins only. Deletes all of the API user's keys, so they stop working immediately, then deactivates the API user.\n\nUse this instead of archiving the API user in the Coperniq UI. Archiving it there deactivates the user but does not delete its keys.\n\nIf any key can't be deleted, the response is a `502` and the API user is left active, so no key is left working on an archived account. Retry the request to finish. Archiving an API user that has no keys left is safe and returns `200`.\n\nArchiving doesn't stop new keys from being created. If the person who created the API user calls `POST /api-keys` again, the API user is reactivated and gets a new key. The archive only returns `200` once it has confirmed no keys are left.\n\nAuthenticate with Basic Auth (your Coperniq email and password), not an API key.\n","tags":["apiKeyManagement"],"parameters":[{"name":"user_id","in":"path","description":"The API user's `id` from `GET /api-users`","required":true,"schema":{"type":"integer","minimum":1}},{"name":"company_id","in":"query","description":"ID of the company to manage. Needed only when the authenticated user belongs to more than one company and the default (their first non-collaborator company) is not the one you want. You must be a superadmin in that company.\nYour company ID can be found in the URL after logging in to the Coperniq UI: `https://app.coperniq.io/{company_id}/inbox`.\n","required":false,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"All of the API user's keys were deleted and the API user was deactivated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArchiveApiUserResponse"}}}},"400":{"description":"`user_id` is not a positive integer, the user is not an API user (archive regular users in the Coperniq UI instead), or the credentials or `company_id` are malformed\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageResponse"}}}},"401":{"description":"Authentication credentials are missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArchiveApiUserRequestUnauthorizedError"}}}},"403":{"description":"The authenticated user is not a superadmin in the company, or doesn't belong to the requested `company_id`\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageResponse"}}}},"404":{"description":"No user with this ID in the company","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageResponse"}}}},"409":{"description":"New keys kept being created for this API user while it was being archived. Stop whatever is creating them, then retry\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArchiveApiUserResponse"}}}},"502":{"description":"Some keys could not be deleted. The API user was not deactivated; retry the request to finish\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArchiveApiUserResponse"}}}}},"security":[{"BasicAuth":[]}]}},"/api-keys/{key_id}":{"delete":{"operationId":"apiKeyManagement_deleteApiKey","summary":"Delete API Key","description":"Delete an API key. Superadmins only. The key stops working immediately.\n\n`key_id` is the key's `id` from `GET /api-keys`, not the key value itself. Passing a key value returns a `400`.\n\nAuthenticate with Basic Auth (your Coperniq email and password), not an API key.\n","tags":["apiKeyManagement"],"parameters":[{"name":"key_id","in":"path","description":"The key's `id` from `GET /api-keys`","required":true,"schema":{"type":"string","pattern":"^key_[0-9a-f]{24}$"}},{"name":"company_id","in":"query","description":"ID of the company to manage. Needed only when the authenticated user belongs to more than one company and the default (their first non-collaborator company) is not the one you want. You must be a superadmin in that company.\nYour company ID can be found in the URL after logging in to the Coperniq UI: `https://app.coperniq.io/{company_id}/inbox`.\n","required":false,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"The key was deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteApiKeyResponse"}}}},"400":{"description":"`key_id` is not a valid key ID (for example, a key value was passed instead), or the credentials or `company_id` are malformed\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageResponse"}}}},"401":{"description":"Authentication credentials are missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteApiKeyRequestUnauthorizedError"}}}},"403":{"description":"The authenticated user is not a superadmin in the company, or doesn't belong to the requested `company_id`\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageResponse"}}}},"404":{"description":"No API key with this ID in the company","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageResponse"}}}},"502":{"description":"The key could not be removed from the API gateway, so nothing was deleted. Retry the request\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageResponse"}}}}},"security":[{"BasicAuth":[]}]}}},"tags":[{"name":"authentication"},{"name":"apiKeyManagement"}],"servers":[{"url":"https://api.coperniq.io/v1","description":"Production server"}],"components":{"schemas":{"ApiKeyResponse":{"type":"object","properties":{"token":{"type":"string","description":"API key (token) for authenticating future requests"},"companyId":{"type":"integer","description":"Company identifier"},"description":{"type":"string","description":"Description of the API key"},"name":{"type":"string","description":"Name of the API key"},"email":{"type":"string","format":"email","description":"Email address of the user who created the API key"},"id":{"type":"integer","description":"API user identifier"}},"title":"ApiKeyResponse"},"GetApiKeyRequestBadRequestError":{"type":"object","properties":{"message":{"type":"string"}},"title":"GetApiKeyRequestBadRequestError"},"GetApiKeyRequestUnauthorizedError":{"type":"object","properties":{"error":{"type":"string"}},"title":"GetApiKeyRequestUnauthorizedError"},"GetApiKeyRequestForbiddenError":{"type":"object","properties":{"message":{"type":"string"}},"title":"GetApiKeyRequestForbiddenError"},"ApiKey":{"type":"object","properties":{"id":{"type":"string","pattern":"^key_[0-9a-f]{24}$","description":"Non-secret identifier for the key. Pass it to `DELETE /api-keys/{key_id}`."},"keyPreview":{"type":"string","description":"The last 4 characters of the key, masked, so you can recognize which key this is."},"name":{"type":"string","description":"Name of the API key"},"description":{"type":["string","null"],"description":"Description of the API key"},"userId":{"type":"integer","description":"ID of the API user (service account) the key belongs to"},"createdById":{"type":["integer","null"],"description":"ID of the user who created the key"},"isEnabled":{"type":"boolean","description":"Whether the key is enabled"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"description":"An API key in the company. The key value itself is never returned. `id` is a non-secret fingerprint of the key, used to delete it.\n","title":"ApiKey"},"MessageResponse":{"type":"object","properties":{"message":{"type":"string"}},"title":"MessageResponse"},"ListApiKeysRequestUnauthorizedError":{"type":"object","properties":{"error":{"type":"string"}},"title":"ListApiKeysRequestUnauthorizedError"},"ApiUser":{"type":"object","properties":{"id":{"type":"integer","description":"API user ID. Pass it to `POST /api-users/{user_id}/archive`."},"email":{"type":"string","format":"email"},"firstName":{"type":"string"},"lastName":{"type":"string"},"isActive":{"type":["boolean","null"],"description":"Whether the API user is active in this company. `false` once archived."},"lastSeenAt":{"type":["string","null"],"format":"date-time","description":"When this API user last made a request, accurate to about an hour. `null` if it has never been used. Tracked per API user, not per key."},"createdAt":{"type":"string","format":"date-time"}},"description":"An API user, the service account that API keys are issued to.","title":"ApiUser"},"ListApiUsersRequestUnauthorizedError":{"type":"object","properties":{"error":{"type":"string"}},"title":"ListApiUsersRequestUnauthorizedError"},"ArchiveApiUserResponse":{"type":"object","properties":{"success":{"type":"boolean"},"deletedKeyCount":{"type":"integer","description":"Number of the API user's keys deleted by this request"},"failedKeyCount":{"type":"integer","description":"Number of the API user's keys that could not be deleted"},"userDeactivated":{"type":"boolean","description":"Whether the API user was deactivated"},"message":{"type":"string","description":"Present when `success` is `false`"}},"title":"ArchiveApiUserResponse"},"ArchiveApiUserRequestUnauthorizedError":{"type":"object","properties":{"error":{"type":"string"}},"title":"ArchiveApiUserRequestUnauthorizedError"},"DeleteApiKeyResponse":{"type":"object","properties":{"success":{"type":"boolean"},"id":{"type":"string","description":"The deleted key's ID"},"dbDeleted":{"type":"boolean","description":"The key was deleted in Coperniq. This is what stops it from working."},"awsDeleted":{"type":"boolean","description":"The key was removed from the API gateway. `false` means there was no gateway key to remove (for example, it had already been removed); the key still no longer works, because `dbDeleted` is `true`.\n"}},"title":"DeleteApiKeyResponse"},"DeleteApiKeyRequestUnauthorizedError":{"type":"object","properties":{"error":{"type":"string"}},"title":"DeleteApiKeyRequestUnauthorizedError"}},"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic"}}}}