# ApiKeys ## List API keys for the tenant > Returns all API key definitions stored in \`security.yml\`.\ > Key hashes are never included in responses.\ > \ > \## Authorization\ > Requires \`tenant.apiKey:read\` scope. ```json {"openapi":"3.1.1","info":{"title":"Neostore internal API","version":"v1"},"tags":[{"name":"ApiKeys"}],"servers":[{"url":"https://app.neostore.cloud","description":"Production Server"},{"url":"https://app-qa.neostore.cloud","description":"Staging Server"}],"security":[{"admin-bearer":["ScopedAuthorizeRequirement"]},{"apiKey":["ScopedAuthorizeRequirement"]}],"components":{"securitySchemes":{"admin-bearer":{"type":"oauth2","flows":{"implicit":{"authorizationUrl":"https://auth.neostore.cloud/authorize?audience=https://app.neostore.cloud/api/","scopes":{}}}},"apiKey":{"type":"apiKey","name":"X-API-KEY","in":"header"}},"schemas":{"ApiKeyDefinition":{"required":["enabled","name","permissions"],"type":"object","properties":{"name":{"type":"string","description":"Key name identifier."},"enabled":{"type":"boolean","description":"Whether this key is currently active."},"permissions":{"type":"array","items":{"type":"string"},"description":"List of permission scopes granted to this key. Use `[\"*\"]` for full tenant-admin access."}},"additionalProperties":false,"description":"API key definition returned by list and get endpoints.\nThe key hash is never exposed."},"ApiKeyCreatedResponse":{"required":["token"],"type":"object","allOf":[{"$ref":"#/components/schemas/ApiKeyDefinition"}],"properties":{"token":{"type":"string","description":"Plaintext API key. Copy and store it immediately — it will not be shown again."}},"additionalProperties":false,"description":"Returned once after a successful key creation.\nThe `Token` field contains the plaintext API key and will never be retrievable again."}}},"paths":{"/api/{tenantId}/admin/apiKeys":{"get":{"tags":["ApiKeys"],"summary":"List API keys for the tenant","description":"Returns all API key definitions stored in `security.yml`.\nKey hashes are never included in responses.\n \n## Authorization\nRequires `tenant.apiKey:read` scope.","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API keys returned.","content":{"text/plain":{"schema":{"type":"array","items":{"oneOf":[{"description":"API key definition returned by list and get endpoints.\nThe key hash is never exposed.","$ref":"#/components/schemas/ApiKeyDefinition"},{"$ref":"#/components/schemas/ApiKeyCreatedResponse"}],"description":"API key definition returned by list and get endpoints.\nThe key hash is never exposed."}}},"application/json":{"schema":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/ApiKeyDefinition"},{"$ref":"#/components/schemas/ApiKeyCreatedResponse"}],"description":"API key definition returned by list and get endpoints.\nThe key hash is never exposed."}}},"text/json":{"schema":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/ApiKeyDefinition"},{"$ref":"#/components/schemas/ApiKeyCreatedResponse"}],"description":"API key definition returned by list and get endpoints.\nThe key hash is never exposed."}}}}}}}}}} ``` ## Create a new API key > Generates a cryptographically secure token, stores its SHA-256 hash in \`security.yml\`,\ > and returns the plaintext token in the response.\ > \*\*The token is only returned once — copy it immediately.\*\*\ > \ > \## Authorization\ > Requires \`tenant.apiKey:write\` scope. ```json {"openapi":"3.1.1","info":{"title":"Neostore internal API","version":"v1"},"tags":[{"name":"ApiKeys"}],"servers":[{"url":"https://app.neostore.cloud","description":"Production Server"},{"url":"https://app-qa.neostore.cloud","description":"Staging Server"}],"security":[{"admin-bearer":["ScopedAuthorizeRequirement"]},{"apiKey":["ScopedAuthorizeRequirement"]}],"components":{"securitySchemes":{"admin-bearer":{"type":"oauth2","flows":{"implicit":{"authorizationUrl":"https://auth.neostore.cloud/authorize?audience=https://app.neostore.cloud/api/","scopes":{}}}},"apiKey":{"type":"apiKey","name":"X-API-KEY","in":"header"}},"schemas":{"CreateApiKeyRequest":{"required":["name"],"type":"object","properties":{"name":{"minLength":1,"type":"string","description":"Key name. Only alphanumeric characters, hyphens, underscores and dots are allowed."},"enabled":{"type":"boolean","description":"Whether this key is active. Defaults to `true`."},"permissions":{"type":"array","items":{"type":"string"},"description":"List of permission scopes granted to this key. Use `[\"*\"]` for full access."}},"additionalProperties":false,"description":"Request body to create an API key."},"ApiKeyCreatedResponse":{"required":["token"],"type":"object","allOf":[{"$ref":"#/components/schemas/ApiKeyDefinition"}],"properties":{"token":{"type":"string","description":"Plaintext API key. Copy and store it immediately — it will not be shown again."}},"additionalProperties":false,"description":"Returned once after a successful key creation.\nThe `Token` field contains the plaintext API key and will never be retrievable again."},"ApiKeyDefinition":{"required":["enabled","name","permissions"],"type":"object","properties":{"name":{"type":"string","description":"Key name identifier."},"enabled":{"type":"boolean","description":"Whether this key is currently active."},"permissions":{"type":"array","items":{"type":"string"},"description":"List of permission scopes granted to this key. Use `[\"*\"]` for full tenant-admin access."}},"additionalProperties":false,"description":"API key definition returned by list and get endpoints.\nThe key hash is never exposed."},"ProblemDetails":{"type":"object","properties":{"type":{"type":["null","string"]},"title":{"type":["null","string"]},"status":{"type":["null","integer"],"format":"int32"},"detail":{"type":["null","string"]},"instance":{"type":["null","string"]}},"additionalProperties":{}},"HttpValidationProblemDetails":{"type":"object","allOf":[{"$ref":"#/components/schemas/ProblemDetails"}],"properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"additionalProperties":{}}}},"paths":{"/api/{tenantId}/admin/apiKeys":{"post":{"tags":["ApiKeys"],"summary":"Create a new API key","description":"Generates a cryptographically secure token, stores its SHA-256 hash in `security.yml`,\nand returns the plaintext token in the response.\n**The token is only returned once — copy it immediately.**\n \n## Authorization\nRequires `tenant.apiKey:write` scope.","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"description":"Request body to create an API key.","$ref":"#/components/schemas/CreateApiKeyRequest"}},"text/json":{"schema":{"description":"Request body to create an API key.","$ref":"#/components/schemas/CreateApiKeyRequest"}},"application/*+json":{"schema":{"description":"Request body to create an API key.","$ref":"#/components/schemas/CreateApiKeyRequest"}}},"required":true},"responses":{"201":{"description":"API key created. Response includes the one-time plaintext token.","content":{"text/plain":{"schema":{"description":"Returned once after a successful key creation.\nThe `Token` field contains the plaintext API key and will never be retrievable again.","$ref":"#/components/schemas/ApiKeyCreatedResponse"}},"application/json":{"schema":{"description":"Returned once after a successful key creation.\nThe `Token` field contains the plaintext API key and will never be retrievable again.","$ref":"#/components/schemas/ApiKeyCreatedResponse"}},"text/json":{"schema":{"description":"Returned once after a successful key creation.\nThe `Token` field contains the plaintext API key and will never be retrievable again.","$ref":"#/components/schemas/ApiKeyCreatedResponse"}}}},"400":{"description":"Name is invalid or permissions are missing.","content":{"text/plain":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"text/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}},"409":{"description":"A key with this name already exists.","content":{"text/plain":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"text/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}}}}}}} ``` ## Get a specific API key > Returns the API key definition identified by keyName.\ > The key hash is never returned.\ > \ > \## Authorization\ > Requires \`tenant.apiKey:read\` scope. ```json {"openapi":"3.1.1","info":{"title":"Neostore internal API","version":"v1"},"tags":[{"name":"ApiKeys"}],"servers":[{"url":"https://app.neostore.cloud","description":"Production Server"},{"url":"https://app-qa.neostore.cloud","description":"Staging Server"}],"security":[{"admin-bearer":["ScopedAuthorizeRequirement"]},{"apiKey":["ScopedAuthorizeRequirement"]}],"components":{"securitySchemes":{"admin-bearer":{"type":"oauth2","flows":{"implicit":{"authorizationUrl":"https://auth.neostore.cloud/authorize?audience=https://app.neostore.cloud/api/","scopes":{}}}},"apiKey":{"type":"apiKey","name":"X-API-KEY","in":"header"}},"schemas":{"ApiKeyDefinition":{"required":["enabled","name","permissions"],"type":"object","properties":{"name":{"type":"string","description":"Key name identifier."},"enabled":{"type":"boolean","description":"Whether this key is currently active."},"permissions":{"type":"array","items":{"type":"string"},"description":"List of permission scopes granted to this key. Use `[\"*\"]` for full tenant-admin access."}},"additionalProperties":false,"description":"API key definition returned by list and get endpoints.\nThe key hash is never exposed."},"ApiKeyCreatedResponse":{"required":["token"],"type":"object","allOf":[{"$ref":"#/components/schemas/ApiKeyDefinition"}],"properties":{"token":{"type":"string","description":"Plaintext API key. Copy and store it immediately — it will not be shown again."}},"additionalProperties":false,"description":"Returned once after a successful key creation.\nThe `Token` field contains the plaintext API key and will never be retrievable again."},"ProblemDetails":{"type":"object","properties":{"type":{"type":["null","string"]},"title":{"type":["null","string"]},"status":{"type":["null","integer"],"format":"int32"},"detail":{"type":["null","string"]},"instance":{"type":["null","string"]}},"additionalProperties":{}},"HttpValidationProblemDetails":{"type":"object","allOf":[{"$ref":"#/components/schemas/ProblemDetails"}],"properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"additionalProperties":{}}}},"paths":{"/api/{tenantId}/admin/apiKeys/{keyName}":{"get":{"tags":["ApiKeys"],"summary":"Get a specific API key","description":"Returns the API key definition identified by keyName.\nThe key hash is never returned.\n \n## Authorization\nRequires `tenant.apiKey:read` scope.","parameters":[{"name":"keyName","in":"path","required":true,"schema":{"type":"string"}},{"name":"tenantId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key returned.","content":{"text/plain":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiKeyDefinition"},{"$ref":"#/components/schemas/ApiKeyCreatedResponse"}],"description":"API key definition returned by list and get endpoints.\nThe key hash is never exposed."}},"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiKeyDefinition"},{"$ref":"#/components/schemas/ApiKeyCreatedResponse"}],"description":"API key definition returned by list and get endpoints.\nThe key hash is never exposed."}},"text/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiKeyDefinition"},{"$ref":"#/components/schemas/ApiKeyCreatedResponse"}],"description":"API key definition returned by list and get endpoints.\nThe key hash is never exposed."}}}},"404":{"description":"API key not found.","content":{"text/plain":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"text/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}}}}}}} ``` ## Update an API key > Replaces the \`enabled\` and \`permissions\` fields of the key.\ > The key name and the stored hash are not changed.\ > \ > \## Authorization\ > Requires \`tenant.apiKey:write\` scope. ```json {"openapi":"3.1.1","info":{"title":"Neostore internal API","version":"v1"},"tags":[{"name":"ApiKeys"}],"servers":[{"url":"https://app.neostore.cloud","description":"Production Server"},{"url":"https://app-qa.neostore.cloud","description":"Staging Server"}],"security":[{"admin-bearer":["ScopedAuthorizeRequirement"]},{"apiKey":["ScopedAuthorizeRequirement"]}],"components":{"securitySchemes":{"admin-bearer":{"type":"oauth2","flows":{"implicit":{"authorizationUrl":"https://auth.neostore.cloud/authorize?audience=https://app.neostore.cloud/api/","scopes":{}}}},"apiKey":{"type":"apiKey","name":"X-API-KEY","in":"header"}},"schemas":{"UpdateApiKeyRequest":{"required":["enabled"],"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether this key is active."},"permissions":{"type":"array","items":{"type":"string"},"description":"New list of permission scopes. Use `[\"*\"]` for full access."}},"additionalProperties":false,"description":"Request body to update an API key."},"ApiKeyDefinition":{"required":["enabled","name","permissions"],"type":"object","properties":{"name":{"type":"string","description":"Key name identifier."},"enabled":{"type":"boolean","description":"Whether this key is currently active."},"permissions":{"type":"array","items":{"type":"string"},"description":"List of permission scopes granted to this key. Use `[\"*\"]` for full tenant-admin access."}},"additionalProperties":false,"description":"API key definition returned by list and get endpoints.\nThe key hash is never exposed."},"ApiKeyCreatedResponse":{"required":["token"],"type":"object","allOf":[{"$ref":"#/components/schemas/ApiKeyDefinition"}],"properties":{"token":{"type":"string","description":"Plaintext API key. Copy and store it immediately — it will not be shown again."}},"additionalProperties":false,"description":"Returned once after a successful key creation.\nThe `Token` field contains the plaintext API key and will never be retrievable again."},"ProblemDetails":{"type":"object","properties":{"type":{"type":["null","string"]},"title":{"type":["null","string"]},"status":{"type":["null","integer"],"format":"int32"},"detail":{"type":["null","string"]},"instance":{"type":["null","string"]}},"additionalProperties":{}},"HttpValidationProblemDetails":{"type":"object","allOf":[{"$ref":"#/components/schemas/ProblemDetails"}],"properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"additionalProperties":{}}}},"paths":{"/api/{tenantId}/admin/apiKeys/{keyName}":{"put":{"tags":["ApiKeys"],"summary":"Update an API key","description":"Replaces the `enabled` and `permissions` fields of the key.\nThe key name and the stored hash are not changed.\n \n## Authorization\nRequires `tenant.apiKey:write` scope.","parameters":[{"name":"keyName","in":"path","required":true,"schema":{"type":"string"}},{"name":"tenantId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"description":"Request body to update an API key.","$ref":"#/components/schemas/UpdateApiKeyRequest"}},"text/json":{"schema":{"description":"Request body to update an API key.","$ref":"#/components/schemas/UpdateApiKeyRequest"}},"application/*+json":{"schema":{"description":"Request body to update an API key.","$ref":"#/components/schemas/UpdateApiKeyRequest"}}},"required":true},"responses":{"200":{"description":"API key updated.","content":{"text/plain":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiKeyDefinition"},{"$ref":"#/components/schemas/ApiKeyCreatedResponse"}],"description":"API key definition returned by list and get endpoints.\nThe key hash is never exposed."}},"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiKeyDefinition"},{"$ref":"#/components/schemas/ApiKeyCreatedResponse"}],"description":"API key definition returned by list and get endpoints.\nThe key hash is never exposed."}},"text/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiKeyDefinition"},{"$ref":"#/components/schemas/ApiKeyCreatedResponse"}],"description":"API key definition returned by list and get endpoints.\nThe key hash is never exposed."}}}},"400":{"description":"Permissions are missing.","content":{"text/plain":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"text/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}},"404":{"description":"API key not found.","content":{"text/plain":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"text/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}}}}}}} ``` ## Delete an API key > Removes the API key entry from \`security.yml\`. The key immediately stops working.\ > \ > \## Authorization\ > Requires \`tenant.apiKey:write\` scope. ```json {"openapi":"3.1.1","info":{"title":"Neostore internal API","version":"v1"},"tags":[{"name":"ApiKeys"}],"servers":[{"url":"https://app.neostore.cloud","description":"Production Server"},{"url":"https://app-qa.neostore.cloud","description":"Staging Server"}],"security":[{"admin-bearer":["ScopedAuthorizeRequirement"]},{"apiKey":["ScopedAuthorizeRequirement"]}],"components":{"securitySchemes":{"admin-bearer":{"type":"oauth2","flows":{"implicit":{"authorizationUrl":"https://auth.neostore.cloud/authorize?audience=https://app.neostore.cloud/api/","scopes":{}}}},"apiKey":{"type":"apiKey","name":"X-API-KEY","in":"header"}},"schemas":{"ProblemDetails":{"type":"object","properties":{"type":{"type":["null","string"]},"title":{"type":["null","string"]},"status":{"type":["null","integer"],"format":"int32"},"detail":{"type":["null","string"]},"instance":{"type":["null","string"]}},"additionalProperties":{}},"HttpValidationProblemDetails":{"type":"object","allOf":[{"$ref":"#/components/schemas/ProblemDetails"}],"properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"additionalProperties":{}}}},"paths":{"/api/{tenantId}/admin/apiKeys/{keyName}":{"delete":{"tags":["ApiKeys"],"summary":"Delete an API key","description":"Removes the API key entry from `security.yml`. The key immediately stops working.\n \n## Authorization\nRequires `tenant.apiKey:write` scope.","parameters":[{"name":"keyName","in":"path","required":true,"schema":{"type":"string"}},{"name":"tenantId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"API key deleted."},"404":{"description":"API key not found.","content":{"text/plain":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"text/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}}}}}}} ``` --- # 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://docs.thewalletcrew.io/develop/api-reference/advanced/apikeys.md?ask= ``` 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.