# Create a new Template Credential Creates credentials that a Template can use with an external service. `POST` `https://api2.transloadit.com/template_credentials` Replace the example S3 credentials and bucket with your own values. Store credentials only from a trusted backend. ## Request example Run this request in a server-side shell with `curl` and a suitable [bearer token](/docs/api/token-post.md) in `TRANSLOADIT_TOKEN`. If you need a token, expand the setup below. **Need a bearer token?** In a trusted server-side shell with `curl` and `jq`, set `TRANSLOADIT_KEY` and `TRANSLOADIT_SECRET` to your Auth Key and Auth Secret. Keep both credentials and the resulting token secret; never run this setup in browser code. First, create a token with this endpoint’s required scopes. Your Auth Key must already grant those scopes. ```bash if ! TOKEN_RESPONSE="$(curl --fail-with-body -sS \ --request POST \ --url 'https://api2.transloadit.com/token' \ --user "${TRANSLOADIT_KEY:?Set TRANSLOADIT_KEY}:${TRANSLOADIT_SECRET:?Set TRANSLOADIT_SECRET}" \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=client_credentials' \ --data-urlencode 'aud=api2' \ --data-urlencode 'scope=template_credentials:write')"; then printf '%s\n' "$TOKEN_RESPONSE" >&2 exit 1 fi TRANSLOADIT_TOKEN="$(printf '%s' "$TOKEN_RESPONSE" | jq -er '.access_token | strings | select(length > 0)')" || exit 1 ``` Keep this shell open and run the request below. Reuse the token while it remains valid. ```bash curl --fail-with-body -sS --request POST \ --url "https://api2.transloadit.com/template_credentials" \ --header "Authorization: Bearer ${TRANSLOADIT_TOKEN:?Set TRANSLOADIT_TOKEN}" \ --data-urlencode 'params={"name":"s3-production","type":"s3","content":{"key":"YOUR_S3_KEY","secret":"YOUR_S3_SECRET","bucket":"your-bucket","bucket_region":"us-east-1"}}' ``` ## Authentication This endpoint accepts signed `params` or a bearer token. See [Authentication](/docs/api/authentication.md) for setup instructions. Required scope for the Auth Key or bearer token: `template_credentials:write`. Signed requests require both a `signature` and a future `params.auth.expires` timestamp. Bearer tokens do not require either. ## Form fields Content type: `application/x-www-form-urlencoded` * `params` (JSON string), required. A JSON-encoded object whose supported keys are listed below. * `signature` (string). Required for signed requests. Omit this field when using a bearer token. ## Supported keys inside the `params` field Authentication fields in this list apply to signed requests. With a bearer token, you can omit `params.auth` and the separate `signature` field. Compare the authentication-specific request parameters below. [Complete JSON Schema](/api-reference/schemas/template-credentials-post/params-fields.json) `params`: Only the fields listed for this object are accepted. ### `params.auth` (required for signed requests; optional with a bearer token) [`object`](#params-fields-auth-expires) Contains the Transloadit API key and signature-authentication metadata for a Template Credentials request. `params.auth`: Only the fields listed for this object are accepted. #### `params.auth.expires` (required) `string` ISO 8601 expiration timestamp in the future. Required when a request is signed or requires signature authentication; bearer-authenticated requests may omit it. #### `params.auth.key` (required) `string` Transloadit API key used to authenticate requests ### `params.content` (required) `object | string` Key and value pairs for this credential type. Pass a JSON object or a JSON-encoded string that decodes to an object. See [supported credential types](/docs/api/template-credentials-types-get.md) for their fields and [updating credentials](/docs/api/template-credentials-credentials-id-put.md) for preservation and secret-rotation behavior. **Any of the following schemas may apply:** * `object` * **Additional property schema** `any value` * `string` ### `params.name` (required) `string` Name of the Template Credentials. Must be between 3 and 255 characters and contain only letters, digits, dashes, underscores, and dots. Validation pattern (regular expression): `^[A-Za-z\u212a0-9._-]{3,255}$` ### `params.nonce` `string | integer` Unique, random value included in signed request params to make each signature unique and prevent accidental signature reuse. ### `params.type` (required) `string` The service these credentials belong to. On update, resend the existing type unchanged. To use a different service, create another Template Credential. Allowed values (22) * `"ai"` * `"azure"` * `"backblaze"` * `"box"` * `"cloudflare"` * `"companion"` * `"digitalocean"` * `"dropbox"` * `"ftp"` * `"google"` * `"http"` * `"mega"` * `"minio"` * `"rackspace"` * `"s3"` * `"sftp"` * `"supabase"` * `"swift"` * `"tigris"` * `"vimeo"` * `"wasabi"` * `"youtube"` ## Request parameters by authentication method ### With signed params Include your Auth Key as `params.auth.key`. When signing the request, include a future `params.auth.expires` timestamp and send the signature in the separate `signature` field. The field definitions below use paths inside `params`. [Complete JSON Schema](/api-reference/schemas/template-credentials-post/signed-params.json) `params`: Only the fields listed for this object are accepted. Uses the field definitions above: [`params.auth`](#params-fields-auth), [`params.content`](#params-fields-content), [`params.name`](#params-fields-name), [`params.nonce`](#params-fields-nonce), [`params.type`](#params-fields-type) ### With a bearer token Send the bearer token in the `Authorization` header. You can omit `params.auth` and the separate `signature` field. Other required parameters still apply. The field definitions below use paths inside `params`. [Complete JSON Schema](/api-reference/schemas/template-credentials-post/bearer-params.json) `params`: Only the fields listed for this object are accepted. Uses the field definitions above: [`params.content`](#params-fields-content), [`params.name`](#params-fields-name), [`params.nonce`](#params-fields-nonce), [`params.type`](#params-fields-type) #### `params.auth` [`object`](#bearer-params-auth-expires) Contains the Transloadit API key and signature-authentication metadata for a Template Credentials request. `params.auth`: Only the fields listed for this object are accepted. ##### `params.auth.expires` `string` ISO 8601 expiration timestamp in the future. Required when a request is signed or requires signature authentication; bearer-authenticated requests may omit it. ##### `params.auth.key` `string` Transloadit API key used to authenticate requests ## Response Here’s an example response body: ```jsonc { "credential": { "account_id": "72a70fba93ce41cba617cfd7c2a44b1a", "content": { "bucket": "your-bucket", "bucket_region": "us-east-1", "key": "YOUR_S3_KEY", "secret": "YOUR_S3_SECRET" }, "created": "2026-09-12T10:00:00.000Z", "deleted": null, "id": "ca7644b763c848e6af4f4ccf3eaea622", "modified": "2026-09-12T10:00:00.000Z", "name": "s3-production", "stringified": "{\"key\":\"YOUR_S3_KEY\",\"secret\":\"YOUR_S3_SECRET\",\"bucket\":\"your-bucket\",\"bucket_region\":\"us-east-1\"}", "type": "s3" }, "message": "Your Template Credentials were successfully created.", "ok": "TEMPLATE_CREDENTIALS_CREATED" } ``` ### 2xx success JSON response body. `application/json` `text/plain; charset=utf-8` #### Response body schema [Complete JSON Schema](/api-reference/schemas/template-credentials-post/response-1-body.json) The response may contain additional fields. ##### `credential` (required) [`object`](#response-1-body-credential-account_id) `credential`: The response contains only the fields listed for this object. ###### `credential.account_id` (required) `string` ###### `credential.content` (required) `object | Array | string | number | boolean | null` [Additional schema details are available in the complete JSON Schema.](/api-reference/schemas/template-credentials-post/response-1-body.json) ###### `credential.created` (required) `number | string | null` **Any of the following schemas may apply:** * `number | string` * `null` ###### `credential.deleted` (required) `number | string | null` **Any of the following schemas may apply:** * `number | string` * `null` ###### `credential.id` (required) `string` ###### `credential.modified` (required) `number | string | null` **Any of the following schemas may apply:** * `number | string` * `null` ###### `credential.name` (required) `string` ###### `credential.stringified` (required) `string` ###### `credential.type` (required) `string` ##### `message` (required) `string` (minimum length: 1) ##### `ok` (required) `string` (always: "TEMPLATE\_CREDENTIALS\_CREATED") ### Error response JSON response body. `application/json` `text/plain; charset=utf-8` #### Response body schema [Complete JSON Schema](/api-reference/schemas/template-credentials-post/response-2-body.json) At least one of these properties is required: error, message, reason The response may contain additional fields. ##### `assembly_id` `string` ##### `error` `string` (minimum length: 1) ##### `http_code` `number | string` * `number` * `string` [Validation pattern (regular expression)](/api-reference/schemas/template-credentials-post/response-2-body.json) ##### `message` `string` Human-readable explanation of the error. Its wording can vary; use the `error` code when handling a specific failure. ##### `reason` `null | string | number | boolean | Array | object` **Any of the following schemas may apply:** * `null` * `string` * `number` * `boolean` * `Array` * **Array item schema** `any value` * `object` * **Additional property schema** `any value` ### HTTP 400 JSON response body. `application/json` `text/plain; charset=utf-8` #### Response body schema [Complete JSON Schema](/api-reference/schemas/template-credentials-post/response-3-body.json) **Named errors and the general error format** * **error: "TEMPLATE\_CREDENTIALS\_NOT\_CREATED"** Your Template Credentials could not be created. The response may contain additional fields. * **`error` (required)** `string` (always: "TEMPLATE\_CREDENTIALS\_NOT\_CREATED") * **`http_code`** `number` (always: 400) * **`message`** `string` Human-readable explanation of the error. Its wording can vary; use the `error` code when handling a specific failure. * **General error format** [See the general error response fields.](#response-2-body)