Authentication Fields#

Overview#

Authentication fields are simply what you need from the user to get started authenticating their API calls. For example, when a user tries to authenticate your service:

auth fields for user

You can see what it will be powered by a developer set up like:

auth fields in developer

Additionally, these user-provided variables will be passed in with the bundle for usage in scripting. For example, the above screenshots would translate to:

{
  "account_name": "myaccount",
  "api_key": "123456789"
}

You can use Auth Mappings to put your Auth Fields to use in Basic Auth, Digest Auth, HTTP headers and query strings.

Let's look at each of the options you define for a single Auth Field.

Authentication Fields Options#

Key#

This is somewhat arbitrary but you should pick a good, short key name because you'll need to include it elsewhere in the developer interface as {{key}} using the variable syntax. Needs to be at least two characters long, start with an alpha, and only contain a-z, A-Z, 0-9 or _.

Example:
(you may not need all of these)

  • api_key an API Key which you give to your users somewhere inside your service. Allows Zapier to authenticate on their behalf
  • account_name an account name which you use to build the API Request URL (perhaps as a subdomain: https://{{account_name}}.example.com/api/v1/)

Label#

This will show up just above the text input field as a human-readable name. You don't need to be super descriptive here; you can provide more details and information about this field in the Help Text field.

Example:
API Key, Account Name

label help default

Required#

Pretty easy concept; most all auth fields should be required. You really shouldn't ask for non-essential information as an auth field.

Help Text#

Smaller text which appears under the Label of the field. You can type longer directions here. A common pattern for Auth Field Help Text is to tell the user where in your interface they can find their API Key.

Example:
The API Key for your account, you can find this by going to your Basecamp Profile page, clicking settings, then API Keys.

Default#

If you specify a default value, the actual field will be pre-filled with this value when the user goes to add a new authentication for your service. If the user clears out a required auth field which had a default set, they will receive an error. Optional fields that are missing a value will use the default every time.

Most auth fields will not have a default.

Example:
choice_b (if you use the choices feature detailed below)

Static Dropdowns#

You can create a dropdown-style select box by giving us a comma-separated list of choices. This works well in conjunction with the default value option above.

Example:
choice_a,choice_b,choice_c or Yesterday, Today, Tomorrow

simple static dropdown

If you would like to provide a label for the raw value of each choice, you can also use the raw|label,raw|label syntax instead.

Example:
1|Option 1,2|Option 2

simple static dropdown as key-value pairs

Subdomain Format#

If you need the user to supply an account name (or similar) which gets translated into a subdomain (or similar) URL format, we recommend you take advantage of this feature. It helps guide the user with what to type in.

Example:
https://,{{input}},.yourdomain.com/ will create:

subdomain format

Note: don't forget the commas!

↑ Was this documentation useful? Yes No
Get Help