# Encrypt Data API

> Encrypt any value with the encrypt data system API of API Maker, using the transfer key of your secret or a key of your own, and get a string a client or a later call can decrypt.

Source: https://docs.apimaker.dev/v1/docs/apis-all/system-apis/system-generated-encrypt-data-api.html

Encrypts a string, a number, an object or an array and answers the encrypted text. By default it uses `encryptionAlgorithmFETransfer` and `secretFETransfer` of the default [secret](https://docs.apimaker.dev/v1/docs/secrets/secrets.html) : the key you share with your frontend or mobile app, so the two sides can exchange encrypted data.

| | |
|---|---|
| Method | POST |
| URL | `/api/system-api/admin/encrypt-data` : `admin` is the user path of your account |
| Body | `{ data, algorithm?, pass? }` |
| Answer | `data` : the encrypted string |
| From code | [`g.sys.system.encrypt`](https://docs.apimaker.dev/v1/examples/sys/system/encrypt.html) |

## The call

**Body**

```json
{ "data": { "name": "Joseph", "card": "4111 1111 1111 1111" } }
```

**Answer**

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

| Key | Meaning |
|---|---|
| `data` | Required. Any JSON value. It is serialised before encryption, so [decrypt](https://docs.apimaker.dev/v1/docs/apis-all/system-apis/system-generated-decrypt-data-api.html) gives the same type back. |
| `algorithm` | `AES` (default from the secret), `RC4` or `TRIPLEDES`. |
| `pass` | Your own key, instead of `secretFETransfer` of the secret. |

- The keys come from the default secret of the account, unless the body gives its own `algorithm` and `pass`.

## From code

```typescript
const text = await g.sys.system.encrypt({ name: 'Joseph' });            // with the transfer key of the secret
const mine = await g.sys.system.encrypt('hello', T.EEncryptionAlgorithm.AES, 'my-own-key');
```

## Good to know

- Fields of a table are encrypted at rest with `conversions: { encryption: true }` in the [schema](https://docs.apimaker.dev/v1/docs/schema/schema.html), with the `secret` key of the secret, not this API.
- To send an encrypted request body, see [encrypted payloads](https://docs.apimaker.dev/v1/docs/features/security-features.html#encrypted-request-payloads) ; to get an encrypted answer, the header [`x-am-get-encrypted-data`](https://docs.apimaker.dev/v1/docs/apis-all/header/requestHeader.html#x-am-get-encrypted-data).

## 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, for example an unknown `algorithm`. |
| `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)