# Get Secret API

> Read one or several keys of a secret by their path with the get secret system API of API Maker - connection strings, API keys of external services, your own keys - from the default secret or a named one.

Source: https://docs.apimaker.dev/v1/docs/apis-all/system-apis/system-generated-get-secret-by-name-api.html

Reads values of a [secret](https://docs.apimaker.dev/v1/docs/secrets/secrets.html) by their path : `common.encryptionAlgorithm`, `stripe.apiKey`… One key gives its value, several give an array in the same order.

| | |
|---|---|
| Method | POST |
| URL | `/api/system-api/admin/get-secret-by-name` : `admin` is the user path of your account |
| Body | `{ keys }` ; from code also `fromSecretName` |
| Answer | `data` : the value, or an array of values |
| From code | [`g.sys.system.getSecret`](https://docs.apimaker.dev/v1/examples/sys/system/getSecret.html) |

## The call

**Body : one key**

```json
{ "keys": "stripe.apiKey" }
```

**Answer**

```json
{ "success": true, "statusCode": 200, "data": "sk_live_…" }
```

**Body : several keys**

```json
{ "keys": [ "stripe.apiKey", "common.connectionString.mysql_8" ] }
```

**Answer**

```json
{ "success": true, "statusCode": 200, "data": [ "sk_live_…", "mysql://…" ] }
```

- `keys` is the full path in the secret object, with dots. A path to an object gives the object.
- Over HTTP the default secret of the account answers. From code, `fromSecretName` reads another secret of the account by its name ; over HTTP that key is ignored.

## From code

```typescript
const key = await g.sys.system.getSecret('stripe.apiKey');
const [ key2, cs ] = await g.sys.system.getSecret([ 'stripe.apiKey', 'common.connectionString.mysql_8' ]);
const staging = await g.sys.system.getSecret('stripe.apiKey', 'staging');   // from the secret named staging
```

## Good to know

- Secrets are never in Git and never in the answer of another API : this API is the way to read them, and it is a sensitive one. Grant it to the groups which need it, or read the secret from your code only (`NO_ACCESS` custom APIs).

## Access and settings

- Over HTTP, a system API answers once its [settings](https://docs.apimaker.dev/v1/docs/settings/systemApiSettings.html) give it `apiAccessType: TOKEN_ACCESS` (the token of an API user whose [group](https://docs.apimaker.dev/v1/docs/apis-security/api-group-permission.html) grants this system API, in `x-am-authorization`) or `IS_PUBLIC`. Without settings it is `NO_ACCESS` : your code calls it through `g.sys`, the admin panel tests it, and an HTTP call is refused.
- The settings can also cache the answer or require person tokens (`authProviders`) ; [pre and post hooks](https://docs.apimaker.dev/v1/docs/apis-all/hooks/preHook-api.html) run around it like around any API.
- The [request headers](https://docs.apimaker.dev/v1/docs/apis-all/header/requestHeader.html) apply : `x-am-response-case`, `x-am-content-type-response`, `x-am-internationalization`, `x-am-tenant-username`…

## Errors

| Code | When |
|---|---|
| `400` | The body is wrong : the message names the missing or invalid key. |
| `401` | No valid API user token, or the API is `NO_ACCESS` : `You are not authorized to access this API.` |
| `403` | No group grants this system API. |

## Related

- [All APIs at a glance](https://docs.apimaker.dev/v1/docs/apis-all/overview.html) · [Response format](https://docs.apimaker.dev/v1/docs/apis-all/response-format.html) · [System API settings](https://docs.apimaker.dev/v1/docs/settings/systemApiSettings.html) · [System APIs from code](https://docs.apimaker.dev/v1/examples/sys/system/system.html)