> ## Documentation Index
> Fetch the complete documentation index at: https://ona.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# List Secrets

> Lists secrets

`Unary` · [`Secrets`](https://ona.com/docs/api-reference/generated/secret/overview)

Lists secrets

Use this method to:

* View all project secrets
* View all user secrets

### Examples

* List project secrets:

  Shows all secrets for a project.

  ```yaml theme={null}
  filter:
    scope:
      projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
  pagination:
    pageSize: 20
  ```

* List user secrets:

  Shows all secrets for a user.

  ```yaml theme={null}
  filter:
    scope:
      userId: "123e4567-e89b-12d3-a456-426614174000"
  pagination:
    pageSize: 20
  ```

## Endpoint

```text theme={null}
POST /api/gitpod.v1.SecretService/ListSecrets
```

Send a Bearer token as described in [Authentication](https://ona.com/docs/api-reference.md#authenticate-requests). If your organization uses a custom management-plane domain, replace `https://app.ona.com` with that domain.

## Request example

```bash cURL theme={null}
export ONA_HOST=https://app.ona.com
export ONA_API_KEY=<your-token>

curl --request POST \
  --url "$ONA_HOST/api/gitpod.v1.SecretService/ListSecrets" \
  --header "Authorization: Bearer $ONA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "pagination": {
    "pageSize": 1
  }
}'
```

```python Python theme={null}
import gitpod.v1.pagination_pb2 as pagination_pb2
import gitpod.v1.secret_pb2 as secret_pb2
from ona_sdk import create_client_from_env

ona = create_client_from_env()
request = secret_pb2.ListSecretsRequest(
    pagination=pagination_pb2.PaginationRequest(
        page_size=1,
    ),
)
response = ona.services.secret.list_secrets(request)
print(response)
```

```typescript TypeScript theme={null}
import { create } from "@bufbuild/protobuf";
import { createClientFromEnv } from "@gitpod/sdk";
import { ListSecretsRequestSchema } from "@gitpod/sdk/gitpod/v1/secret_pb";

async function main() {
  const ona = createClientFromEnv();
  const request = create(ListSecretsRequestSchema, {
    pagination: {
      pageSize: 1,
    },
  });
  const response = await ona.services.secret.listSecrets(request);
  console.log(response);
}

main().catch(console.error);
```

```go Go theme={null}
package main

import (
	"context"
	"fmt"
	"log"

	"connectrpc.com/connect"
	"github.com/gitpod-io/gitpod-sdk-go/sdk"
	gitpodpb "github.com/gitpod-io/gitpod-sdk-go/v1"
)

func main() {
	ona, err := sdk.NewFromEnv()
	if err != nil {
		log.Fatal(err)
	}

	request := connect.NewRequest(&gitpodpb.ListSecretsRequest{
		Pagination: &gitpodpb.PaginationRequest{
			PageSize: 1,
		},
	})
	response, err := ona.Services.Secret.ListSecrets(context.Background(), request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response.Msg)
}
```

```json Request body theme={null}
{
  "pagination": {
    "pageSize": 1
  }
}
```

## Request

`gitpod.v1.ListSecretsRequest`

| Field | Type | Required | Description |
| - | - | - | - |
| `pagination` | [PaginationRequest](#type-gitpod-v1-pagination-request) | No | pagination contains the pagination options for listing environments |
| `filter` | [Filter](#type-gitpod-v1-list-secrets-request-filter) | No | |

## Response

`gitpod.v1.ListSecretsResponse`

| Field | Type | Required | Description |
| - | - | - | - |
| `pagination` | [PaginationResponse](#type-gitpod-v1-pagination-response) | No | pagination contains the pagination options for listing secrets |
| `secrets` | array of [Secret](#type-gitpod-v1-secret) | No | |

## Related types

> [accordion] Filter
>
> `gitpod.v1.ListSecretsRequest.Filter`
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `projectIds` | array of string | No | **Deprecated.** project\_ids filters the response to only Secrets used by these Project IDs Deprecated: use scope instead. Values in project\_ids will be ignored. Constraints: `repeated.items.string.uuid=true, repeated.max_items=25, repeated.min_items=0`. |
> | `scope` | [SecretScope](#type-gitpod-v1-secret-scope) | No | scope is the scope of the secrets to list |

> [accordion] PaginationRequest
>
> `gitpod.v1.PaginationRequest`
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `pageSize` | integer | No | Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100. Constraints: `int32.gte=0, int32.lte=100`. |
> | `token` | string | No | Token for the next set of results that was returned as next\_token of a PaginationResponse |

> [accordion] PaginationResponse
>
> `gitpod.v1.PaginationResponse`
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `nextToken` | string | No | Token passed for retrieving the next set of results. Empty if there are no more results |

> [accordion] Secret
>
> `gitpod.v1.Secret`
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `id` | string | No | Constraints: `string.uuid=true`. |
> | `name` | string | No | Name of the secret for humans. |
> | `projectId` | string | No | **Deprecated.** The Project ID this Secret belongs to Deprecated: use scope instead Constraints: `string.uuid=true`. |
> | `createdAt` | RFC 3339 timestamp | No | |
> | `updatedAt` | RFC 3339 timestamp | No | |
> | `creator` | [Subject](#type-gitpod-v1-subject) | No | creator is the identity of the creator of the secret |
> | `filePath` | string | One of `mount` | absolute path to the file where the secret is mounted |
> | `environmentVariable` | boolean | One of `mount` | secret will be created as an Environment Variable with the same name as the secret |
> | `containerRegistryBasicAuthHost` | string | One of `mount` | secret will be mounted as a registry secret Constraints: `string.uri=true`. |
> | `apiOnly` | boolean | One of `mount` | api\_only indicates the secret is only available via API/CLI |
> | `scope` | [SecretScope](#type-gitpod-v1-secret-scope) | No | |
> | `credentialProxy` | [CredentialProxy](#type-gitpod-v1-secret-credential-proxy) | No | credential\_proxy configures transparent credential injection via the credential proxy. When set, the credential proxy intercepts HTTPS traffic to the target hosts and replaces the dummy mounted value with the real value in the specified HTTP header. The real secret value is never exposed in the environment. This field is orthogonal to mount - a secret can be both mounted and proxied at the same time. |
> | `source` | [Source](#type-gitpod-v1-secret-source) | No | Source of the secret |

> [accordion] CredentialProxy
>
> CredentialProxy describes how the credential proxy should inject this
> secret into outgoing HTTPS requests.
>
> `gitpod.v1.Secret.CredentialProxy`
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `targetHosts` | array of string | No | target\_hosts lists the hostnames to intercept (for example "github.com" or "\*.github.com"). Wildcards are subdomain-only and do not match the apex domain. |
> | `header` | string | No | header is the HTTP header name to inject (e.g. "Authorization"). |

> [accordion] Source
>
> Source defines
>
> `gitpod.v1.Secret.Source`
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `verbatim` | boolean | No | |
> | `oidcJfrog` | OidcJFrog | No | |

> [accordion] SecretScope
>
> `gitpod.v1.SecretScope`
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `projectId` | string | No | project\_id is the Project ID this Secret belongs to Constraints: `string.uuid=true`. |
> | `userId` | string | No | user\_id is the User ID this Secret belongs to Constraints: `string.uuid=true`. |
> | `organizationId` | string | No | organization\_id is the Organization ID this Secret belongs to Constraints: `string.uuid=true`. |
> | `serviceAccountId` | string | No | service\_account\_id is the Service Account ID this Secret belongs to Constraints: `string.uuid=true`. |

> [accordion] Subject
>
> `gitpod.v1.Subject`
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `id` | string | No | id is the UUID of the subject Constraints: `ignore=1, string.uuid=true`. |
> | `principal` | [Principal](#enum-gitpod-v1-principal) | No | Principal is the principal of the subject Constraints: `enum.defined_only=true`. |

> [accordion] Principal
>
> | Value | Number | Description |
> | - | -: | - |
> | `PRINCIPAL_UNSPECIFIED` | 0 | |
> | `PRINCIPAL_ACCOUNT` | 1 | |
> | `PRINCIPAL_USER` | 2 | |
> | `PRINCIPAL_RUNNER` | 3 | |
> | `PRINCIPAL_ENVIRONMENT` | 4 | |
> | `PRINCIPAL_SERVICE_ACCOUNT` | 5 | |
> | `PRINCIPAL_RUNNER_MANAGER` | 6 | |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.