1Password SDK concepts
Authentication
1Password SDKs currently support authentication with 1Password Service Accounts, which are designed to authenticate automated processes to 1Password.
You can choose which vaults a service account can access and its permissions in each vault, allowing you to follow the principle of least privilege in your project.
Autofill behavior
Which credentials 1Password suggests
When you create a Login or Password item, use the following IDs and field types for the credentials you want 1Password to suggest and fill:
| ID | fieldType | Description |
|---|---|---|
username | Text | The username associated with the login. |
password | Concealed | The password associated with the login. |
See an example of how to create a Login item.
Where a login is suggested and filled
The Item struct for Login and Password items contains an optional list of websites, so you can manage where 1Password autofills your credentials. Autofill behavior options include:
| Autofill behavior | Description |
|---|---|
AnywhereOnWebsite | Default. 1Password autofills credentials on any page that’s part of the website, including subdomains. |
ExactDomain | 1Password autofills credentials only if the domain (hostname and port) is an exact match. |
Never | 1Password never autofills credentials on this website. |
Document file
A document file is a file stored in 1Password as a Document item. You can read, save, and replace document files saved in 1Password using the SDKs.
Item categories
Items in 1Password have a category that determines some characteristics about the item, like the fields available by default and whether 1Password suggests the item when you sign in to a website. Learn more about the different types of items you can save in 1Password. See supported item categories.
Item states
ItemOverview exposes one of two states: Active or Archived.
| Item state | Description |
|---|---|
| Active | An item located inside a vault. (Default) |
| Archived | An item that has been moved to the Archive. 1Password doesn’t include archived items in search results or suggest them when you fill in apps and browsers. You can keep archived items as long as you’d like. |
Field file
A field file is a file attachment saved in a 1Password item. You can read, save, and remove file attachments saved in 1Password using the SDKs.
Field types
1Password SDKs currently support operations on the following field types. You can only retrieve and make changes to supported field types.
| Field type | Description |
|---|---|
Address | An address. Specify each part of the address in the field's details. Don't set or edit the address field's value directly. |
Concealed | A secret value that 1Password conceals by default, like a password, API key, or credit card PIN. |
CreditCardNumber | A credit card number. |
CreditCardType | Type of credit card. For example Visa, Mastercard, or American Express. |
Date | A date, formatted as YYYY-MM-DD. |
Email | An email address. |
Menu | A menu of predefined options included in certain item types, like Database, Server, Email Account, and Wireless Router items. |
MonthYear | A month-year combination, formatted as MM/YYYY. |
Notes | A note about an item. |
Phone | A phone number. |
Text | A text string. |
Totp | A one-time password field. Must be either a valid TOTP URL or a one-time password seed. |
Url | A web address to copy or open in your default web browser, not used for autofill behavior. You can add autofill websites to set where 1Password suggests and fills a Login or Password item. |
Reference | The valid ID of another item in the same vault. |
SSHKey | Must be a valid SSH private key – a decrypted, PEM-encoded string. SSH key fields can only be added to items with the SSH Key category. You can add one SSH key field per item. 1Password will generate a public key, fingerprint, and key type which are stored in the SSH key field details. |
If an item contains information saved in unsupported field types, you won't be able to update or delete the item.
See supported functionality for more information.
Query parameters
otp
You can use the otp (or totp) attribute query parameter to retrieve one-time passwords with the Resolve function.
Append the ?attribute=otp query parameter to a secret reference that points to the field where your one-time password is stored. For example:
ssh-format
You can use the ssh-format attribute query parameter to fetch a private SSH key in OpenSSH format using the Resolve function.
Append the ?ssh-format=openssh query parameter to a secret reference that points to the field where your SSH private key is stored. For example:
Rate limits
1Password Service Accounts have hourly and daily rate limits. These also apply while using a service account with an SDK. Learn more about service account rate limits.
SDK client
When you initialize an SDK, you create a 1Password SDK client instance and pass your configuration parameters to the SDK core. You can instantiate multiple SDK clients sequentially or in parallel using the same or different service account tokens.
Secret references
1Password SDKs allow you to use secret reference URIs to avoid the risk of exposing plaintext secrets in your code. Secret references reflect changes you make in 1Password, so when you use the SDK to load a secret you get the latest value.
Secret references use the following syntax:
Learn more about secret references.
State management
The 1Password SDK client sets up an authenticated session with the 1Password servers and automatically refreshes it whenever it expires. As a result, you don't need to worry about managing your authentication and session keys.
Unique identifiers
A unique identifier (ID) is a string of 26 numbers and letters that can be used to identify a 1Password object, like a vault, item, section, or field. IDs only change if you move an item to a different vault.
1Password SDKs require you to use IDs rather than names to refer to 1Password objects while performing item management operations.
You can get IDs by listing vaults and items.