{ "openapi": "3.0.3", "info": { "title": "Push Security Partner API", "version": "v1", "description": "## Overview\n\nThe Push Security Partner API provides programmatic access to the tenants you manage as a Push partner. It lets you drive tenant lifecycle from your own systems rather than through the partner console.\n\nThis API adheres to RESTful principles, featuring resource-oriented URLs that are predictable and easy to navigate. It uses JSON-formatted request bodies and responses along with standard HTTP response codes, authentication methods, and HTTP verbs.\n\nEvery operation is scoped to the partner the API key belongs to. A tenant managed by another partner is indistinguishable from one that does not exist.\n\n[Rate limits](#section/Rate-limits) are in place to ensure consistent performance for all partners.\n\n## Authentication\n\nTo interact with the Push Security Partner API, you'll need a partner API key for authentication. To create or manage your partner API keys, go to the API keys page in the Push partner console.\n\nPartner API keys are prefixed with `pspk_`. They are distinct from the tenant API keys used with the Push Security REST API, which are prefixed with `psak_`, and the two are not interchangeable.\n\nWhen generating a new key, you have two permission levels to choose from: `Read only` and `Full access`. A `Read only` key can make GET requests only — listing tenants, reading a tenant and listing a tenant's API keys. Creating, updating or deleting a tenant, and generating a SAML setup link, all require a `Full access` key.\n\nTo authenticate your API requests, include a header named `x-api-key` and set its value to your partner API key.\n\nAll API calls must be made over HTTPS.\n\n### Regions\n\nEach Push region is independent: a tenant exists in one region, and a partner API key authenticates only against the region it was issued in. Use the server for the region your tenants are in.\n\n### Revoking a key\n\nDeleting or disabling a partner API key, and removing a partner's access to the Partner API, all take effect within **10 minutes** rather than immediately. Authorization decisions are cached for that period. Plan key rotation around that window.\n\n## Rate limits\n\nThe Push Security Partner API enforces rate limiting to ensure equitable access and maintain performance.\n\nLimits apply **per API key**, not per partner, so each key you issue gets its own allowance:\n\n| Limit | Value |\n|-------|-------|\n| Requests per second | 10, with a temporary burst capacity of an additional 10 for brief intervals |\n| Requests per day | 5,000 |\n\nIf you surpass the rate limit, the API returns a 429 status code. If you exhaust the daily quota, further requests are rejected until the quota resets.\n\n## Errors\n\nThe Push Security Partner API uses standard HTTP response codes to signal the outcome of an API call. Here's what you need to know:\n\n2xx codes: These indicate that your request was successful.\n\n4xx codes: A client-side issue, usually because something is missing or incorrect in your request.\n\n5xx codes: These suggest a problem on our end, although these occurrences are infrequent.\n\n### Common Response Codes\n\n| HTTP Code | Description |\n|-----------|---------------------------------------------------------|\n| 200 OK | Your request was successfully processed. |\n| 400 Bad Request | Your request is missing something or is incorrect. Double-check your parameters. |\n| 403 Forbidden | Your partner account does not have access to the Partner API, the key is unknown or disabled, or you used a `Read only` key on a write operation. |\n| 404 Not Found | The tenant does not exist or is not managed by your partner account, or the tenant's API key does not exist. |\n| 409 Conflict | The tenant is being deleted (`TENANT_DELETE_IN_PROGRESS`), already has 20 API keys (`TOO_MANY_API_KEYS`), or already has a SAML connection (`CONNECTION_ALREADY_EXISTS`). |\n| 429 Too Many Requests | You've exceeded the rate limits or the daily quota. Consider implementing exponential backoffs in your API calls. |\n| 500 Server Error | Something's not right on our end. |\n| 502 Bad Gateway | A tenant's sign-in could not be provisioned or updated, or its SAML setup link could not be created. Nothing was changed, so the request can be retried. |\n| 503 Service Unavailable | The API is temporarily down for maintenance. Retry later. |\n\n## Versioning\n\nYou're currently working with version 1 of the Push Security Partner API. Should there be any breaking changes in the future, we'll bump up the API version number. If you hold an active API key, we'll send you notifications over email about the deprecation date for the older version.\n", "contact": { "name": "support", "email": "support@pushsecurity.com", "url": "https://pushsecurity.com/contact/" }, "termsOfService": "https://pushsecurity.com/legal/terms/", "license": { "url": "https://pushsecurity.com/legal/terms/", "name": "Commercial" } }, "x-amazon-apigateway-request-validators": { "all": { "validateRequestBody": true, "validateRequestParameters": true }, "params": { "validateRequestBody": false, "validateRequestParameters": true }, "none": { "validateRequestBody": false, "validateRequestParameters": false } }, "x-amazon-apigateway-api-key-source": "AUTHORIZER", "servers": [ { "url": "https://eu1.partner-api.pushsecurity.com", "description": "EU region" }, { "url": "https://us1.partner-api.pushsecurity.com", "description": "US region" } ], "paths": { "/v1/tenants": { "get": { "summary": "List tenants", "x-amazon-apigateway-integration": { "uri": { "Fn::Sub": "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${PartnerApisStackHandlerFunction.Arn}/invocations" }, "responses": { "default": { "statusCode": "200" } }, "passthroughBehavior": "never", "httpMethod": "POST", "contentHandling": "CONVERT_TO_TEXT", "type": "aws_proxy" }, "tags": [ "Tenants" ], "operationId": "get-tenants", "description": "Retrieve the tenants managed by your partner account.\nTenants that are being deleted are included, flagged with `deleteInProgress`. Results are paginated: when `paging.moreResults` is `true`, pass `paging.nextToken` as the `nextToken` query parameter to fetch the next page.", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "description": "Used for pagination. Number of tenants to return." }, { "in": "query", "name": "nextToken", "schema": { "type": "string" }, "description": "Used for pagination. The `paging.nextToken` returned with the previous page." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/Tenant" } }, "paging": { "type": "object", "properties": { "moreResults": { "type": "boolean", "description": "Whether there are more results available.", "example": false }, "nextToken": { "type": "string", "description": "Start of the next page that can be used as the `nextToken` for the next request.", "nullable": true } } } } } } } }, "400": { "description": "Bad Request. `limit` is not an integer between 1 and 100, `nextToken` is not a valid page token, or an unrecognised query parameter was sent." }, "403": { "description": "Forbidden" }, "503": { "description": "Service Unavailable. The API is temporarily down for maintenance." } } }, "post": { "summary": "Create tenant", "x-amazon-apigateway-integration": { "uri": { "Fn::Sub": "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${PartnerApisStackHandlerFunction.Arn}/invocations" }, "responses": { "default": { "statusCode": "200" } }, "passthroughBehavior": "never", "httpMethod": "POST", "contentHandling": "CONVERT_TO_TEXT", "type": "aws_proxy" }, "tags": [ "Tenants" ], "operationId": "post-tenants", "description": "Create a tenant managed by your partner account. Requires a `Full access` key.\nThe tenant's members can sign in with a username and password, Google or Microsoft. Tenant names do not have to be unique across your tenants.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 3, "maxLength": 75, "description": "Human-readable name for the tenant. Letters, digits, spaces and `( ) , . ' -` are allowed.", "example": "Acme Corporation" }, "metadata": { "$ref": "#/components/schemas/TenantMetadata" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tenant" } } } }, "400": { "description": "Bad Request. `name` is missing or not 3 to 75 characters, `metadata` is `null` or exceeds its limits, or an unrecognised field was sent." }, "403": { "description": "Forbidden. The key is `Read only`." }, "502": { "description": "Bad Gateway. The tenant's sign-in could not be provisioned. No tenant was created, so the request can be retried." }, "503": { "description": "Service Unavailable. The API is temporarily down for maintenance." } } } }, "/v1/tenants/{tenantId}": { "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "name": "tenantId", "in": "path", "required": true, "description": "Unique identifier for the tenant." } ], "get": { "summary": "Get tenant", "x-amazon-apigateway-integration": { "uri": { "Fn::Sub": "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${PartnerApisStackHandlerFunction.Arn}/invocations" }, "responses": { "default": { "statusCode": "200" } }, "passthroughBehavior": "never", "httpMethod": "POST", "contentHandling": "CONVERT_TO_TEXT", "type": "aws_proxy" }, "tags": [ "Tenants" ], "operationId": "get-tenant", "description": "Retrieve a tenant managed by your partner account.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tenant" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found. The tenant does not exist, or is not managed by your partner account." }, "409": { "description": "Conflict. The tenant is being deleted (`TENANT_DELETE_IN_PROGRESS`)." }, "503": { "description": "Service Unavailable. The API is temporarily down for maintenance." } } }, "patch": { "summary": "Update tenant", "x-amazon-apigateway-integration": { "uri": { "Fn::Sub": "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${PartnerApisStackHandlerFunction.Arn}/invocations" }, "responses": { "default": { "statusCode": "200" } }, "passthroughBehavior": "never", "httpMethod": "POST", "contentHandling": "CONVERT_TO_TEXT", "type": "aws_proxy" }, "tags": [ "Tenants" ], "operationId": "patch-tenants-id", "description": "Rename a tenant, replace its metadata, or both. Requires a `Full access` key.\nA field that is omitted is left unchanged. `metadata` replaces the tenant's metadata as a whole rather than merging into it, so send `{}` to clear it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "name": { "type": "string", "minLength": 3, "maxLength": 75, "description": "Human-readable name for the tenant. Letters, digits, spaces and `( ) , . ' -` are allowed.", "example": "Acme Corporation" }, "metadata": { "$ref": "#/components/schemas/TenantMetadata" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tenant" } } } }, "400": { "description": "Bad Request. The body is empty, `name` is `null` or not 3 to 75 characters, `metadata` is `null` or exceeds its limits, or an unrecognised field was sent." }, "403": { "description": "Forbidden. The key is `Read only`." }, "404": { "description": "Not Found. The tenant does not exist, or is not managed by your partner account." }, "409": { "description": "Conflict. The tenant is being deleted (`TENANT_DELETE_IN_PROGRESS`)." }, "502": { "description": "Bad Gateway. The tenant's name could not be updated with its sign-in provider. Nothing was changed, so the request can be retried." }, "503": { "description": "Service Unavailable. The API is temporarily down for maintenance." } } }, "delete": { "summary": "Delete tenant", "x-amazon-apigateway-integration": { "uri": { "Fn::Sub": "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${PartnerApisStackHandlerFunction.Arn}/invocations" }, "responses": { "default": { "statusCode": "200" } }, "passthroughBehavior": "never", "httpMethod": "POST", "contentHandling": "CONVERT_TO_TEXT", "type": "aws_proxy" }, "tags": [ "Tenants" ], "operationId": "delete-tenants-id", "description": "Delete a tenant and all of its data. Requires a `Full access` key.\nDeletion is asynchronous. Until it completes the tenant is still listed, flagged with `deleteInProgress`, and any other request for it returns a 409.", "responses": { "200": { "description": "OK. The tenant is being deleted." }, "403": { "description": "Forbidden. The key is `Read only`." }, "404": { "description": "Not Found. The tenant does not exist, or is not managed by your partner account." }, "409": { "description": "Conflict. The tenant is already being deleted (`TENANT_DELETE_IN_PROGRESS`)." }, "503": { "description": "Service Unavailable. The API is temporarily down for maintenance." } } } }, "/v1/tenants/{tenantId}/apiKeys": { "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "name": "tenantId", "in": "path", "required": true, "description": "Unique identifier for the tenant." } ], "get": { "summary": "List tenant API keys", "x-amazon-apigateway-integration": { "uri": { "Fn::Sub": "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${PartnerApisStackHandlerFunction.Arn}/invocations" }, "responses": { "default": { "statusCode": "200" } }, "passthroughBehavior": "never", "httpMethod": "POST", "contentHandling": "CONVERT_TO_TEXT", "type": "aws_proxy" }, "tags": [ "Tenants" ], "operationId": "get-tenants-id-apiKeys", "description": "Retrieve a tenant's API keys, including those created in the Push console. The keys themselves are never returned. A tenant has at most 20 keys, so the list is not paginated.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/TenantApiKey" } } } } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found. The tenant does not exist, or is not managed by your partner account." }, "409": { "description": "Conflict. The tenant is being deleted (`TENANT_DELETE_IN_PROGRESS`)." }, "503": { "description": "Service Unavailable. The API is temporarily down for maintenance." } } }, "post": { "summary": "Create tenant API key", "x-amazon-apigateway-integration": { "uri": { "Fn::Sub": "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${PartnerApisStackHandlerFunction.Arn}/invocations" }, "responses": { "default": { "statusCode": "200" } }, "passthroughBehavior": "never", "httpMethod": "POST", "contentHandling": "CONVERT_TO_TEXT", "type": "aws_proxy" }, "tags": [ "Tenants" ], "operationId": "post-tenants-id-apiKeys", "description": "Create an API key for a tenant's REST API. Requires a `Full access` key.\nThe key is returned in `apiKey` in this response only, so store it securely. It can take a few seconds to start working. A tenant can have at most 20 keys, including those created in the Push console.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "friendlyName": { "type": "string", "maxLength": 50, "description": "Name for the key. Letters, digits, spaces and `( ) , . ' -` are allowed.", "example": "SIEM integration" }, "permissions": { "type": "string", "enum": [ "FULL_ACCESS", "READ_ONLY" ], "description": "What the key can do. A `READ_ONLY` key can only make `GET` requests.", "example": "READ_ONLY" } }, "required": [ "friendlyName", "permissions" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/TenantApiKey" }, { "type": "object", "properties": { "apiKey": { "type": "string", "description": "The API key. It is returned only once.", "example": "psak_0123456789abcdef0123456789abcdef" } }, "required": [ "apiKey" ] } ] } } } }, "400": { "description": "Bad Request. `friendlyName` is missing, longer than 50 characters or contains a character that is not allowed, `permissions` is missing or not recognised, or an unrecognised field was sent." }, "403": { "description": "Forbidden. The key is `Read only`." }, "404": { "description": "Not Found. The tenant does not exist, or is not managed by your partner account." }, "409": { "description": "Conflict. The tenant is being deleted (`TENANT_DELETE_IN_PROGRESS`), or already has 20 API keys (`TOO_MANY_API_KEYS`)." }, "503": { "description": "Service Unavailable. The API is temporarily down for maintenance." } } } }, "/v1/tenants/{tenantId}/apiKeys/{apiKeyId}": { "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "name": "tenantId", "in": "path", "required": true, "description": "Unique identifier for the tenant." }, { "schema": { "type": "string", "format": "uuid" }, "name": "apiKeyId", "in": "path", "required": true, "description": "Unique identifier for the API key." } ], "delete": { "summary": "Delete tenant API key", "x-amazon-apigateway-integration": { "uri": { "Fn::Sub": "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${PartnerApisStackHandlerFunction.Arn}/invocations" }, "responses": { "default": { "statusCode": "200" } }, "passthroughBehavior": "never", "httpMethod": "POST", "contentHandling": "CONVERT_TO_TEXT", "type": "aws_proxy" }, "tags": [ "Tenants" ], "operationId": "delete-tenants-id-apiKeys-apiKeyId", "description": "Delete one of a tenant's API keys, including one created in the Push console. Requires a `Full access` key. The key stops working within 10 minutes.", "responses": { "200": { "description": "OK. The API key was deleted." }, "403": { "description": "Forbidden. The key is `Read only`." }, "404": { "description": "Not Found. The tenant does not exist or is not managed by your partner account, or the API key does not exist or belongs to another tenant." }, "409": { "description": "Conflict. The tenant is being deleted (`TENANT_DELETE_IN_PROGRESS`)." }, "503": { "description": "Service Unavailable. The API is temporarily down for maintenance." } } } }, "/v1/tenants/{tenantId}/samlSetupLink": { "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "name": "tenantId", "in": "path", "required": true, "description": "Unique identifier for the tenant." } ], "post": { "summary": "Create tenant SAML setup link", "x-amazon-apigateway-integration": { "uri": { "Fn::Sub": "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${PartnerApisStackHandlerFunction.Arn}/invocations" }, "responses": { "default": { "statusCode": "200" } }, "passthroughBehavior": "never", "httpMethod": "POST", "contentHandling": "CONVERT_TO_TEXT", "type": "aws_proxy" }, "tags": [ "Tenants" ], "operationId": "post-tenants-id-samlSetupLink", "description": "Create a link that a tenant's IT administrator can follow to set up SAML single sign-on for the tenant. Requires a `Full access` key.\nThe SAML connection is created when the administrator completes the setup. Once it exists, further requests return a 409.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "description": "Takes no fields. The body can be omitted or sent as `{}`." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "setupLink": { "type": "string", "format": "uri", "description": "The link for the tenant's administrator to follow.", "example": "https://login.pushsecurity.com/self-service/saml?ticket=abc123" } }, "required": [ "setupLink" ] } } } }, "400": { "description": "Bad Request. An unrecognised field was sent." }, "403": { "description": "Forbidden. The key is `Read only`." }, "404": { "description": "Not Found. The tenant does not exist, or is not managed by your partner account." }, "409": { "description": "Conflict. The tenant is being deleted (`TENANT_DELETE_IN_PROGRESS`), or already has a SAML connection (`CONNECTION_ALREADY_EXISTS`)." }, "502": { "description": "Bad Gateway. The tenant's sign-in provider could not create the link. Nothing was changed, so the request can be retried." }, "503": { "description": "Service Unavailable. The API is temporarily down for maintenance." } } } } }, "components": { "securitySchemes": { "x-api-key": { "name": "x-api-key", "type": "apiKey", "in": "header", "description": "Partner API key authentication", "x-amazon-apigateway-authtype": "token", "x-amazon-apigateway-authorizer": { "type": "token", "identitySource": "method.request.header.x-api-key", "authorizerUri": { "Fn::Sub": "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${PartnerApisStackAuthorizerFunction.Arn}/invocations" }, "identityValidationExpression": "pspk_[a-f0-9]{32}", "authorizerResultTtlInSeconds": 600 } } }, "schemas": { "TenantMetadata": { "title": "Tenant Metadata", "type": "object", "description": "Key/value metadata set by the partner that manages this tenant.\nOnly present for tenants managed by a partner. When a partner manages the tenant but has set no metadata, it is present as an empty object rather than omitted or null.\nA partner may set at most 10 entries, with keys up to 40 characters and values up to 256 characters.", "additionalProperties": { "type": "string" }, "example": { "customerRef": "ACME-001", "region": "emea" } }, "Tenant": { "title": "Tenant", "type": "object", "description": "A Push tenant managed by your partner account.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the tenant.", "example": "0c2e1b84-ee1d-4ef9-a3b3-4b2e1d5c8f27" }, "name": { "type": "string", "description": "Human-readable name for the tenant. Names are not unique across your tenants.", "example": "Acme Corporation" }, "metadata": { "$ref": "#/components/schemas/TenantMetadata" }, "creationTimestamp": { "type": "integer", "format": "int64", "description": "When the tenant was created, as a UNIX timestamp in seconds.", "example": 1718100000 }, "deleteInProgress": { "type": "boolean", "description": "Whether the tenant is currently being deleted.\nThis can only be `true` in the tenant list: reading a single tenant that is being deleted returns a 409 instead. Once deleted the tenant will no longer be listed.", "example": false } }, "required": [ "id", "name", "metadata", "creationTimestamp", "deleteInProgress" ] }, "TenantApiKey": { "title": "Tenant API key", "type": "object", "description": "An API key for a tenant's own REST API. Keys created in the Push console are included alongside those created through the Partner API.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the API key.", "example": "5b0c6a7e-3f1d-4c2b-9e8a-7d6f5e4c3b2a" }, "friendlyName": { "type": "string", "description": "Name given to the API key when it was created.", "example": "SIEM integration" }, "creatorEmail": { "type": "string", "description": "Email address of whoever created the key. For a key created through the Partner API, this is the creator of the partner API key that was used.", "example": "jane@msp.example.com" }, "permissions": { "type": "string", "enum": [ "FULL_ACCESS", "READ_ONLY" ], "description": "What the key can do. A `READ_ONLY` key can only make `GET` requests.", "example": "FULL_ACCESS" }, "enabled": { "type": "boolean", "description": "Whether the key can be used.", "example": true }, "creationTimestamp": { "type": "integer", "format": "int64", "description": "When the key was created, as a UNIX timestamp in seconds.", "example": 1718100000 }, "lastUsedTimestamp": { "type": "integer", "format": "int64", "nullable": true, "description": "When the key was last used, as a UNIX timestamp in seconds. `null` if never used.", "example": 1718186400 } }, "required": [ "id", "friendlyName", "creatorEmail", "permissions", "enabled", "creationTimestamp", "lastUsedTimestamp" ] } } }, "x-internal": false, "tags": [ { "name": "Tenants", "description": "These objects represent the Push tenants that your partner account manages." } ], "security": [ { "x-api-key": [] } ] }