> For the complete documentation index, see [llms.txt](https://docs.p0.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.p0.dev/integrations/resource-integrations/custom-resource.md).

# Custom resource

Manage access to an internal system you own, or to any system that P0 has no built-in integration for.

The Custom resource integration lets you manage access to internal, on-premises, or third-party systems that P0 has no built-in integration for. When P0 grants or revokes a user's access, it calls a function you run in AWS Lambda or Google Cloud Run, and your function provisions or removes that access in your system.

Running the function in your own cloud account gives you:

* **No credentials to store:** P0 authenticates to your function with AWS IAM or a Google Cloud identity token, so there are no secrets to rotate.
* **Full control:** your function decides how to filter, transform, or enrich each request before it reaches your system.
* **Logs in your account:** you trace and troubleshoot calls in your own cloud logging.
* **Any language or runtime:** your function is a web endpoint that accepts the payload below.

Lambda and Cloud Run functions receive the same event payload, defined by the OpenAPI specification below. You can reuse the same logic on either provider, or move between them.

To install the integration, see [Installing a custom resource integration](https://docs.p0.dev/integrations/resource-integrations/custom-resource/installing-a-custom-resource-integration.md).

## Configuration parameters

You set these parameters when you install the integration. The examples connect users to an internal customer administration app at a multi-tenant B2B company.

<table><thead><tr><th width="179.36224365234375">Parameter</th><th>Description</th><th>Example value</th></tr></thead><tbody><tr><td>Resource identifier</td><td>The ID of the system you are integrating. P0 sends it to your function in each event. Use an ID without spaces, in camel case by convention.</td><td>customerAdminApp</td></tr><tr><td>Application name</td><td>The name users see when they request access</td><td>Internal Customer Admin App</td></tr></tbody></table>

## OpenAPI specification

This specification describes the API endpoint you must implement to create a custom resource integration in P0.

{% file src="/files/h4c1fevDppTGIF9xm7jt" %}

## Handle access request event

> Grant a user access to a resource

```json
{"openapi":"3.0.4","info":{"title":"Custom Integration Access Lifecycle API","version":"0.0.1"},"tags":[{"name":"access","description":"Handle access requests for your resources"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"P0 generates a keypair during integration setup. Each http request sent by P0 to your endpoints contains a JWT signed with the private key in the Authorization header. Your endpoints must use the public key retrieved during integration setup, to decode the JWT   and verify its claims. The claims are: sub (Subject) iss (Issuer), aud (Audience), iat (Issued At), exp (Expiry)"}},"schemas":{"AccessEvent":{"oneOf":[{"$ref":"#/components/schemas/GrantEvent"},{"$ref":"#/components/schemas/RevokeEvent"},{"$ref":"#/components/schemas/ListEvent"}],"discriminator":{"propertyName":"eventType"}},"GrantEvent":{"required":["eventType","data"],"type":"object","properties":{"eventType":{"type":"string","enum":["grant"]},"data":{"$ref":"#/components/schemas/PermissionRequest"}}},"PermissionRequest":{"required":["type","principal","requestor","permission"],"type":"object","properties":{"requestId":{"type":"string","description":"Random identifier for the request generated by P0"},"type":{"type":"string","description":"The value of this field is always going to be the Integration ID value you configured in P0."},"principal":{"type":"string","description":"E-mail address of the principal. Access should be provisioned to the user identified by this email."},"requestor":{"type":"string","description":"E-mail address of the requestor. Different from the principal only if the requestor initiated the access request on behalf of someone else."},"reason":{"type":"string","description":"The reason provided by the requestor"},"permission":{"$ref":"#/components/schemas/Access"}}},"Access":{"required":["item"],"properties":{"item":{"type":"string","description":"The list item selected by the user. The value corresponds to the unique key that identifies the item in your system. This value is derived from the ListItem:identifier field."}}},"RevokeEvent":{"required":["eventType","data"],"type":"object","properties":{"eventType":{"type":"string","enum":["revoke"]},"data":{"$ref":"#/components/schemas/PermissionRequest"}}},"ListEvent":{"required":["eventType"],"type":"object","properties":{"eventType":{"type":"string","enum":["list"]}}},"AccessEventResponse":{"oneOf":[{"$ref":"#/components/schemas/Empty"},{"$ref":"#/components/schemas/ListItems"}]},"Empty":{"type":"object"},"ListItems":{"required":["items"],"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ListItem"}}}},"ListItem":{"required":["label","identifier"],"properties":{"label":{"type":"string","description":"The display label shown to users when they list resources."},"category":{"type":"string","description":"Optional. The category of this item. Results are grouped by the category in listers."},"identifier":{"type":"string","description":"The unique key that identifies the item in your system. Hidden from the user, except in the P0 CLI."}},"description":"An item that can be picked by the user to populate the requested access fields. Filtering the items based on user search term is handled by P0."},"Error":{"type":"object","properties":{"type":{"type":"string","enum":["public","internal"]},"message":{"type":"string"},"errorId":{"type":"string"},"publicMessage":{"type":"string","description":"The message is shown verbatim to the user in the channel they used to create the request  (P0 CLI, Slack, MS Teams, etc.)."}},"required":["type","message"],"description":"If `type` is \"internal\", the `errorId` field must be present. P0 will display a generic message to the user: \"Error in service Internal Customer Admin App: P0 encountered an unknown error. Please contact p0sec-support@example.com for assistance. (Error ID {errorId}).\". If `type` is `public`, the `publicMessage` field must be present. P0 will display its content verbatim to the user. The regular `message` field will be logged in P0 but not displayed to the user. Note: P0 will retry all requests that return an error a few times."}},"responses":{"AccessEventResponse":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessEventResponse"}}}},"ErrorResponse":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/":{"post":{"tags":["access"],"summary":"Handle access request event","description":"Grant a user access to a resource","operationId":"grantRequest","requestBody":{"description":"Grant a user access to a resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessEvent"}}},"required":true},"responses":{"200":{"$ref":"#/components/responses/AccessEventResponse"},"201":{"$ref":"#/components/responses/AccessEventResponse"},"202":{"$ref":"#/components/responses/AccessEventResponse"},"default":{"$ref":"#/components/responses/ErrorResponse"}}}}}}
```

## The AccessEvent object

```json
{"openapi":"3.0.4","info":{"title":"Custom Integration Access Lifecycle API","version":"0.0.1"},"components":{"schemas":{"AccessEvent":{"oneOf":[{"$ref":"#/components/schemas/GrantEvent"},{"$ref":"#/components/schemas/RevokeEvent"},{"$ref":"#/components/schemas/ListEvent"}],"discriminator":{"propertyName":"eventType"}},"GrantEvent":{"required":["eventType","data"],"type":"object","properties":{"eventType":{"type":"string","enum":["grant"]},"data":{"$ref":"#/components/schemas/PermissionRequest"}}},"PermissionRequest":{"required":["type","principal","requestor","permission"],"type":"object","properties":{"requestId":{"type":"string","description":"Random identifier for the request generated by P0"},"type":{"type":"string","description":"The value of this field is always going to be the Integration ID value you configured in P0."},"principal":{"type":"string","description":"E-mail address of the principal. Access should be provisioned to the user identified by this email."},"requestor":{"type":"string","description":"E-mail address of the requestor. Different from the principal only if the requestor initiated the access request on behalf of someone else."},"reason":{"type":"string","description":"The reason provided by the requestor"},"permission":{"$ref":"#/components/schemas/Access"}}},"Access":{"required":["item"],"properties":{"item":{"type":"string","description":"The list item selected by the user. The value corresponds to the unique key that identifies the item in your system. This value is derived from the ListItem:identifier field."}}},"RevokeEvent":{"required":["eventType","data"],"type":"object","properties":{"eventType":{"type":"string","enum":["revoke"]},"data":{"$ref":"#/components/schemas/PermissionRequest"}}},"ListEvent":{"required":["eventType"],"type":"object","properties":{"eventType":{"type":"string","enum":["list"]}}}}}}
```

## The GrantEvent object

```json
{"openapi":"3.0.4","info":{"title":"Custom Integration Access Lifecycle API","version":"0.0.1"},"components":{"schemas":{"GrantEvent":{"required":["eventType","data"],"type":"object","properties":{"eventType":{"type":"string","enum":["grant"]},"data":{"$ref":"#/components/schemas/PermissionRequest"}}},"PermissionRequest":{"required":["type","principal","requestor","permission"],"type":"object","properties":{"requestId":{"type":"string","description":"Random identifier for the request generated by P0"},"type":{"type":"string","description":"The value of this field is always going to be the Integration ID value you configured in P0."},"principal":{"type":"string","description":"E-mail address of the principal. Access should be provisioned to the user identified by this email."},"requestor":{"type":"string","description":"E-mail address of the requestor. Different from the principal only if the requestor initiated the access request on behalf of someone else."},"reason":{"type":"string","description":"The reason provided by the requestor"},"permission":{"$ref":"#/components/schemas/Access"}}},"Access":{"required":["item"],"properties":{"item":{"type":"string","description":"The list item selected by the user. The value corresponds to the unique key that identifies the item in your system. This value is derived from the ListItem:identifier field."}}}}}}
```

## The RevokeEvent object

```json
{"openapi":"3.0.4","info":{"title":"Custom Integration Access Lifecycle API","version":"0.0.1"},"components":{"schemas":{"RevokeEvent":{"required":["eventType","data"],"type":"object","properties":{"eventType":{"type":"string","enum":["revoke"]},"data":{"$ref":"#/components/schemas/PermissionRequest"}}},"PermissionRequest":{"required":["type","principal","requestor","permission"],"type":"object","properties":{"requestId":{"type":"string","description":"Random identifier for the request generated by P0"},"type":{"type":"string","description":"The value of this field is always going to be the Integration ID value you configured in P0."},"principal":{"type":"string","description":"E-mail address of the principal. Access should be provisioned to the user identified by this email."},"requestor":{"type":"string","description":"E-mail address of the requestor. Different from the principal only if the requestor initiated the access request on behalf of someone else."},"reason":{"type":"string","description":"The reason provided by the requestor"},"permission":{"$ref":"#/components/schemas/Access"}}},"Access":{"required":["item"],"properties":{"item":{"type":"string","description":"The list item selected by the user. The value corresponds to the unique key that identifies the item in your system. This value is derived from the ListItem:identifier field."}}}}}}
```

## The ListEvent object

```json
{"openapi":"3.0.4","info":{"title":"Custom Integration Access Lifecycle API","version":"0.0.1"},"components":{"schemas":{"ListEvent":{"required":["eventType"],"type":"object","properties":{"eventType":{"type":"string","enum":["list"]}}}}}}
```

## The PermissionRequest object

```json
{"openapi":"3.0.4","info":{"title":"Custom Integration Access Lifecycle API","version":"0.0.1"},"components":{"schemas":{"PermissionRequest":{"required":["type","principal","requestor","permission"],"type":"object","properties":{"requestId":{"type":"string","description":"Random identifier for the request generated by P0"},"type":{"type":"string","description":"The value of this field is always going to be the Integration ID value you configured in P0."},"principal":{"type":"string","description":"E-mail address of the principal. Access should be provisioned to the user identified by this email."},"requestor":{"type":"string","description":"E-mail address of the requestor. Different from the principal only if the requestor initiated the access request on behalf of someone else."},"reason":{"type":"string","description":"The reason provided by the requestor"},"permission":{"$ref":"#/components/schemas/Access"}}},"Access":{"required":["item"],"properties":{"item":{"type":"string","description":"The list item selected by the user. The value corresponds to the unique key that identifies the item in your system. This value is derived from the ListItem:identifier field."}}}}}}
```

## The Access object

```json
{"openapi":"3.0.4","info":{"title":"Custom Integration Access Lifecycle API","version":"0.0.1"},"components":{"schemas":{"Access":{"required":["item"],"properties":{"item":{"type":"string","description":"The list item selected by the user. The value corresponds to the unique key that identifies the item in your system. This value is derived from the ListItem:identifier field."}}}}}}
```

## The AccessEventResponse object

```json
{"openapi":"3.0.4","info":{"title":"Custom Integration Access Lifecycle API","version":"0.0.1"},"components":{"schemas":{"AccessEventResponse":{"oneOf":[{"$ref":"#/components/schemas/Empty"},{"$ref":"#/components/schemas/ListItems"}]},"Empty":{"type":"object"},"ListItems":{"required":["items"],"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ListItem"}}}},"ListItem":{"required":["label","identifier"],"properties":{"label":{"type":"string","description":"The display label shown to users when they list resources."},"category":{"type":"string","description":"Optional. The category of this item. Results are grouped by the category in listers."},"identifier":{"type":"string","description":"The unique key that identifies the item in your system. Hidden from the user, except in the P0 CLI."}},"description":"An item that can be picked by the user to populate the requested access fields. Filtering the items based on user search term is handled by P0."}}}}
```

## The ListItem object

```json
{"openapi":"3.0.4","info":{"title":"Custom Integration Access Lifecycle API","version":"0.0.1"},"components":{"schemas":{"ListItem":{"required":["label","identifier"],"properties":{"label":{"type":"string","description":"The display label shown to users when they list resources."},"category":{"type":"string","description":"Optional. The category of this item. Results are grouped by the category in listers."},"identifier":{"type":"string","description":"The unique key that identifies the item in your system. Hidden from the user, except in the P0 CLI."}},"description":"An item that can be picked by the user to populate the requested access fields. Filtering the items based on user search term is handled by P0."}}}}
```

## The ListItems object

```json
{"openapi":"3.0.4","info":{"title":"Custom Integration Access Lifecycle API","version":"0.0.1"},"components":{"schemas":{"ListItems":{"required":["items"],"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ListItem"}}}},"ListItem":{"required":["label","identifier"],"properties":{"label":{"type":"string","description":"The display label shown to users when they list resources."},"category":{"type":"string","description":"Optional. The category of this item. Results are grouped by the category in listers."},"identifier":{"type":"string","description":"The unique key that identifies the item in your system. Hidden from the user, except in the P0 CLI."}},"description":"An item that can be picked by the user to populate the requested access fields. Filtering the items based on user search term is handled by P0."}}}}
```

## The Error object

```json
{"openapi":"3.0.4","info":{"title":"Custom Integration Access Lifecycle API","version":"0.0.1"},"components":{"schemas":{"Error":{"type":"object","properties":{"type":{"type":"string","enum":["public","internal"]},"message":{"type":"string"},"errorId":{"type":"string"},"publicMessage":{"type":"string","description":"The message is shown verbatim to the user in the channel they used to create the request  (P0 CLI, Slack, MS Teams, etc.)."}},"required":["type","message"],"description":"If `type` is \"internal\", the `errorId` field must be present. P0 will display a generic message to the user: \"Error in service Internal Customer Admin App: P0 encountered an unknown error. Please contact p0sec-support@example.com for assistance. (Error ID {errorId}).\". If `type` is `public`, the `publicMessage` field must be present. P0 will display its content verbatim to the user. The regular `message` field will be logged in P0 but not displayed to the user. Note: P0 will retry all requests that return an error a few times."}}}}
```

## The Empty object

```json
{"openapi":"3.0.4","info":{"title":"Custom Integration Access Lifecycle API","version":"0.0.1"},"components":{"schemas":{"Empty":{"type":"object"}}}}
```
