Skip to content

docs: Secret object/array inputs #1682

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jul 21, 2025
Merged

docs: Secret object/array inputs #1682

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
944a82f
docs: Secret object/array inputs
mfori Jul 10, 2025
97a13d7
mention sdk versions
mfori Jul 16, 2025
97c991c
Update sources/platform/actors/development/actor_definition/input_sch…
mfori Jul 21, 2025
4983d01
Update sources/platform/actors/development/actor_definition/input_sch…
mfori Jul 21, 2025
5cb88ac
Update sources/platform/actors/development/actor_definition/input_sch…
mfori Jul 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 8 additions & 2 deletions sources/platform/actors/development/actor_definition/input_schema/secret_input.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,15 +37,21 @@ The editor for this input field will then turn into a secret input, and when you

<img src={require("./images/secret-input-editor.png").default} alt="Secret input editor" style={{ width: '100%', maxWidth: '822px' }}/>

When you run the Actor through the API, the system automatically encrypts any input fields marked as secret before saving them to the Actor run's default key-value store.

:::note Type restriction

This is only available for `string` inputs, and the editor type is limited to `textfield` or `textarea`.
This feature supports `string`, `object`, and `array` input types. Available editor types include:

- `hidden` (for any supported input type)
- `textfield` and `textarea` (for string inputs)
- `json` (for `object` and `array` inputs)

:::

## Read secret input fields

When you read the Actor input through `Actor.getInput()`, the encrypted fields are automatically decrypted (starting with the [`apify` package](https://www.npmjs.com/package/apify) version 3.1.0).
When you read the Actor input through `Actor.getInput()`, the encrypted fields are automatically decrypted. Decryption of string fields is supported since [JavaScript SDK](http://docs.apify.loc/sdk/js/) 3.1.0; support for objects and arrays was added in [JavaScript SDK](http://docs.apify.loc/sdk/js/) 3.4.2 and [Python SDK](http://docs.apify.loc/sdk/python/) 2.7.0.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure about the note with starting support for string fields since 3.1.0 is 3 years old

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably safe, it's in the respective git tag: https://github.com/apify/apify-sdk-js/blob/apify%403.1.0/packages/apify/src/actor.ts#L660


<!-- eslint-skip -->
```js
Expand Down
38 changes: 20 additions & 18 deletions sources/platform/actors/development/actor_definition/input_schema/specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -243,16 +243,16 @@ The user provides either a URL or uploads the file to a key-value store (existin

Properties:

| Property | Value | Required | Description |
|----------|--------|-----------|-------------|
| `editor` | One of:<br/>- `textfield`<br/>- `textarea`<br/>- `javascript`<br/>- `python`<br/>- `select`<br/>- `datepicker`<br/>- `fileupload`<br/>- `hidden` | Yes | Visual editor used for the input field. |
| `pattern` | String | No | Regular expression that will be used to validate the input. If validation fails, the Actor will not run. |
| `minLength` | Integer | No | Minimum length of the string. |
| `maxLength` | Integer | No | Maximum length of the string. |
| `enum` | [String] | Required if `editor` is `select` | Using this field, you can limit values to the given array of strings. Input will be displayed as select box. |
| `enumTitles` | [String] | No | Titles for the `enum` keys described. |
| `nullable` | Boolean | No | Specifies whether `null` is an allowed value. |
| `isSecret` | Boolean | No | Specifies whether the input field will be stored encrypted. Only available with `textfield` and `textarea` editors. |
| Property | Value | Required | Description |
|----------|--------|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `editor` | One of:<br/>- `textfield`<br/>- `textarea`<br/>- `javascript`<br/>- `python`<br/>- `select`<br/>- `datepicker`<br/>- `fileupload`<br/>- `hidden` | Yes | Visual editor used for the input field. |
| `pattern` | String | No | Regular expression that will be used to validate the input. If validation fails, the Actor will not run. |
| `minLength` | Integer | No | Minimum length of the string. |
| `maxLength` | Integer | No | Maximum length of the string. |
| `enum` | [String] | Required if `editor` is `select` | Using this field, you can limit values to the given array of strings. Input will be displayed as select box. |
| `enumTitles` | [String] | No | Titles for the `enum` keys described. |
| `nullable` | Boolean | No | Specifies whether `null` is an allowed value. |
| `isSecret` | Boolean | No | Specifies whether the input field will be stored encrypted. Only available with `textfield`, `textarea` and `hidden` editors. |
| `dateType` | One of <ul><li>`absolute`</li><li>`relative`</li><li>`absoluteOrRelative`</li></ul> | No | This property, which is only available with `datepicker` editor, specifies what date format should visual editor accept (The JSON editor accepts any string without validation.).<br/><br/><ul><li>`absolute` value enables date input in `YYYY-MM-DD` format. To parse returned string regex like this can be used: `^(\d{4})-(0[1-9]\|1[0-2])-(0[1-9]\|[12]\d\|3[01])$`.</li><br/><li>`relative` value enables relative date input in <br/>`{number} {unit}` format. <br/>Supported units are: days, weeks, months, years.<br/><br/>The input is passed to the Actor as plain text (e.g., "3 weeks"). To parse it, regex like this can be used: `^(\d+)\s*(day\|week\|month\|year)s?$`.</li><br/><li>`absoluteOrRelative` value enables both absolute and relative formats and user can switch between them. It's up to Actor author to parse a determine actual used format - regexes above can be used to check whether the returned string match one of them.</li></ul><br/>Defaults to `absolute`. |

:::note Regex escape
Expand Down Expand Up @@ -393,14 +393,15 @@ Rendered input:

Properties:

| Property | Value | Required | Description |
| --- | --- | --- | --- |
| `editor` | One of <ul><li>`json`</li><li>`proxy`</li><li>`hidden`</li></ul> | Yes | UI editor used for input. |
| `patternKey` | String | No | Regular expression that will be used <br/>to validate the keys of the object. |
| `patternValue` | String | No | Regular expression that will be used <br/>to validate the values of object. |
| `maxProperties` | Integer | No | Maximum number of properties <br/>the object can have. |
| `minProperties` | Integer | No | Minimum number of properties <br/>the object can have. |
| `nullable` | Boolean | No | Specifies whether null is <br/>an allowed value. |
| Property | Value | Required | Description |
| --- | --- | --- |--------------------------------------------------------------------------------------------------------------|
| `editor` | One of <ul><li>`json`</li><li>`proxy`</li><li>`hidden`</li></ul> | Yes | UI editor used for input. |
| `patternKey` | String | No | Regular expression that will be used <br/>to validate the keys of the object. |
| `patternValue` | String | No | Regular expression that will be used <br/>to validate the values of object. |
| `maxProperties` | Integer | No | Maximum number of properties <br/>the object can have. |
| `minProperties` | Integer | No | Minimum number of properties <br/>the object can have. |
| `nullable` | Boolean | No | Specifies whether null is <br/>an allowed value. |
| `isSecret` | Boolean | No | Specifies whether the input field will be stored encrypted. Only available with `json` and `hidden` editors. |

### Array

Expand Down Expand Up @@ -450,6 +451,7 @@ Properties:
| `uniqueItems` | Boolean | No | Specifies whether the array <br/>should contain only unique values. |
| `nullable` | Boolean | No | Specifies whether null is <br/>an allowed value. |
| `items` | object | No | Specifies format of the items of the array, useful mainly for multiselect (see below) |
| `isSecret` | Boolean | No | Specifies whether the input field will be stored encrypted. Only available with `json` and `hidden` editors. |


Usage of this field is based on the selected editor:
Expand Down