Secrets

TeamPasswords API endpoints are deprecated in v22.4 of this guide, and replaced with SecretsSafe v22.4. TeamPasswords API endpoints remain usable, but will be removed in time.

Quick Navigation

• POST Secrets-Safe/Folders/{folderId:guid}/secrets
• POST Secrets-Safe/Folders/{folderId:guid}/secrets/text
• POST Secrets-Safe/Folders/{folderId:guid}/secrets/file
• PUT Secrets-Safe/Secrets/{secretId:guid}/
• PUT Secrets-Safe/Secrets/{secretId:guid}/text
• PUT Secrets-Safe/Secrets/{secretId:guid}/file
• GET Secrets-Safe/Secrets
• GET Secrets-Safe/Secrets/{secretId:guid}
• GET Secrets-Safe/Folders/{folderId:guid}/secrets
• GET Secrets-Safe/Secrets/{secretId:guid}/text
• GET Secrets-Safe/Secrets/{secretId:guid}/file
• GET Secrets-Safe/Secrets/{secretId:guid}/file/download
• DELETE Secrets-Safe/Secrets/{secretId:guid}/

POST Secrets-Safe/Folders/{folderId:guid}/secrets

Purpose

Creates a secret in the folder by ID.

Required Permissions

Secrets-Safe (Read/Write).

Parameters

folderid: the folder ID (GUID).

Request Body

Content-Type: application/json

{
            Title : string,
            Description : string,
            Username : string,
            Password : string,
            OwnerId : int,
            OwnerType : string,
            Owners : [{ 
            OwnerId : int, 
            Owner : string,
            Email : string,
            }],
            PasswordRuleID : int,
            Notes : string,
         Urls : [{
         Id : Guid,
         CredentialId : Guid,
         Url : String
         }]
       }

Request Body Details

• Max string length for description and password is 256.
• Max string length for notes is 4000.
• Max string length for Url is 2048.
• Required: Title, username, password.
• When OwnerType is set to User, then a list of Owners is required. When OwnerType is set to Group, the OwnerId is required (as the GroupId).
• A password or a PasswordRuleID is required.
  • If a PasswordRuleID is passed in, then a password is generated (based on the Password Policy defined by the PasswordPolicyID).
  • If a password is passed in instead, the same behavior is followed (using that as the password).

Response Body

Content-Type: application/json

[
   {
        Id : Guid,
        Title : string,
        Description : string,
        Username : string,
        Password : string,
        OwnerId : int,
        FolderId : Guid,
        CreatedOn : Datetime,
        CreatedBy : string,
        ModifiedOn : Datetime,
        ModifiedBy : string,
        Owner : string,
        Folder : string,
        FolderPath : string,
        Owners : [{ 
        OwnerId : int, 
        Owner : string,
        Email : string,
        }],
     OwnerType : string,
     Notes : string,   
     Urls : [{
     Id : Guid,
     CredentialId : Guid,
     Url : String
     }]
    }
]

Response Codes

201 - Created

400 - Bad Request

403 - Forbidden

409 - Conflict

For more information, please see Common Response Codes.

POST Secrets-Safe/Folders/{folderId:guid}/secrets/text

Purpose

Creates a text secret in the given folder ID.

Required Permissions

Secrets-Safe (Read/Write).

Parameters

folderid: the folder ID (GUID).

Request Body

Content-Type: application/json

{
                   Title : string,
            Description : string,
            Text : string,
            OwnerId : int,
            OwnerType : string,
            Owners : [{ 
            OwnerId : int, 
            Owner : string,
            Email : string,
            }],
            Notes : string,
            FolderId : Guid,
         Urls : [{
         Id : Guid,
         CredentialId : Guid,
         Url : String
         }]
       }

Request Body Details

• Max string length for Title and Description is 256.
• Max string length for text is 4096.
• Max string length for notes is 4000.
• Max string length for Url is 2048.
• Required: Title, FolderId
• When OwnerType is set to User, then a list of Owners is required. When OwnerType is set to Group, the OwnerId is required (as the GroupId).

Response Body

Content-Type: application/json

[
   {
        Id : Guid,
        Title : string,
        Description : string,
        OwnerId : int,
        FolderId : Guid,
        CreatedOn : Datetime,
        CreatedBy : string,
        ModifiedOn : Datetime,
        ModifiedBy : string,
        Owner : string,
        Folder : string,
        FolderPath : string,
        Owners : [{ 
        OwnerId : int, 
        Owner : string,
        Email : string,
        }],
        OwnerType : string,
        Notes : string, 
     Urls : [{
     Id : Guid,
     CredentialId : Guid,
     Url : String
     }]
     }
]

Response Codes

201 - Created

400 - Bad Request

403 - Forbidden

409 - Conflict.

For more information, please see Common Response Codes.

POST Secrets-Safe/Folders/{folderId:guid}/secrets/file

Purpose

Creates a secret file in the given folder ID.

Required Permissions

Secrets-Safe (Read/Write).

Parameters

folderid: the folder ID (GUID).

Request Body

Content-Type: multipart/form-data

{
            Title : string,
            Description : string,
            OwnerId : int,
            OwnerType : string,
            Owners : [{ 
            OwnerId : int, 
            Owner : string,
            Email : string,
            }],
            Notes : string,
            FileName : string,
         Urls : [{
         Id : Guid,
         CredentialId : Guid,
         Url : String
         }]
       }

Request Body Details

• Max string length for Title, Description, and FileName is 256.
• Max string length for notes is 4000.
• Max string length for Url is 2048.
• Max file size is 5 MB. Size must be greater than 0 MB.
• Required: Title, FolderId, Filename
• When OwnerType is set to User, then a list of Owners is required. When OwnerType is set to Group, the OwnerId is required (as the GroupId).
• When adding the file, the form field name must be "secretmetadata". If the name of the form is anything else, the following error occurs: The multipart Request is missing poarts: key:'form-data'=True, key:'secretmetadata'=False.

Response Body

Content-Type: application/octet-stream

Content Part One - name: form-data, type: binary

Content Part Two - name: secretmetadata, type: string

[
   {
        Id : Guid,
        Title : string,
        Description : string,
        OwnerId : int,
        FolderId : Guid,
        CreatedOn : Datetime,
        CreatedBy : string,
        ModifiedOn : Datetime,
        ModifiedBy : string,
        Owner : string,
        Folder : string,
        FolderPath : string,
        Owners : [{ 
        OwnerId : int, 
        Owner : string,
        Email : string,
        }],
        OwnerType : string,
        Notes : string,
        FileName : string,
        FileHash : string,
     Urls : [{
     Id : Guid,
     CredentialId : Guid,
     Url : String
     }]
   }
]

Response Codes

201 - Created

400 - Bad Request

403 - Forbidden

409 - Conflict

For more information, please see Common Response Codes.

PUT Secrets-Safe/Secrets/{secretId:guid}/

Purpose

Updates a secret based on the given ID.

Required Permissions

Secrets-Safe (Read/Write).

Parameters

SecretId: the secret id (GUID)

Request Body

Content-Type: application/json

{
            FolderId : Guid,
            Title : string,
            Description : string,
            Username : string,
            Password : string,
            OwnerId : int,
            OwnerType : string,  
            Owners : [{
            OwnerId : int,
            Owner : string,
            Email : string,    
            }],        
            PasswordRuleId : int,
            Notes : string,
         Urls : [{
         Id : Guid,
         CredentialId : Guid,
         Url : String
         }]
       }

Request Body Details

• Max string length for description is 256.
• Max string length for notes is 4000.
• Max string length for Url is 2048.
• Required: Title, username, password.
• When OwnerType is set to User, then a list of Owners is required. When OwnerType is set to Group, the OwnerId is required (as the GroupId).
• A password or a PasswordRuleID is required.
  • If a PasswordRuleID is passed in, then a password is generated (based on the Password Policy defined by the PasswordPolicyID).
  • If a password is passed in instead, the same behavior is followed (using that as the password).

Response Body

Content-Type: application/json

[
   {
        Id : Guid,
        Title : string,
        Description : string,
        OwnerId : int,
        FolderId : Guid,
        CreatedOn : Datetime,
        CreatedBy : string,
        ModifiedOn : Datetime,
        ModifiedBy : string,
        Owner : string,
        Folder : string,
        FolderPath : string,
        Owners : [{ 
        OwnerId : int, 
        Owner : string,
        Email : string,
        }],
        OwnerType : string,
        Notes : string,
     Urls : [{
     Id : Guid,
     CredentialId : Guid,
     Url : String
     }]
   }
]

Response Codes

204 - No Content

403 - Forbidden

400 - Bad Request

For more information, please see Common Response Codes.

PUT Secrets-Safe/Secrets/{secretId:guid}/text

Purpose

Updates a secret text based on the given ID.

Required Permissions

Secrets-Safe (Read/Write).

Parameters

SecretId: the secret ID (GUID)

Request Body

Content-Type: application/json

{
            FolderId : Guid,
            Title : string,
            Description : string,
            OwnerId : int,
            OwnerType : string,
            Owners : [{
            OwnerId : int,
            Owner : string,
            Email : string,    
            }],        
            Notes : string,
         Urls : [{
         Id : Guid,
         CredentialId : Guid,
         Url : String
         }]
       }

Request Body Details

• Max string length for description and password is 256.
• Max string length for notes is 4000.
• Max string length for Url is 2048.
• Required: Title.
• When OwnerType is set to User, then a list of Owners is required. When OwnerType is set to Group, the OwnerId is required (as the GroupId).

Response Body

[ 
   {
        Id : Guid,
        Title : string,
        Description : string,
        OwnerId : int,
        FolderId : Guid,
        CreatedOn : Datetime,
        CreatedBy : string,
        ModifiedOn : Datetime,
        ModifiedBy : string,
        Owner : string,
        Folder : string,
        FolderPath : string,
        Owners : [{ 
        OwnerId : int, 
        Owner : string,
        Email : string,
        }],
        OwnerType : string,
        Notes : string, 
     Urls : [{
     Id : Guid,
     CredentialId : Guid,
     Url : String
     }]
      }
]

Response Codes

204 - No Content

400 - Bad Request

403 - Forbidden

For more information, please see Common Response Codes.

PUT Secrets-Safe/Secrets/{secretId:guid}/file

Purpose

Updates a file secret based on the folder ID.

Required Permissions

Secrets-Safe (Read/Write).

Parameters

SecretId: the secret ID (GUID).

Request Body

Content-Type: application/json

{
            FolderId : Guid,
            Title : string,
            Description : string,
            OwnerId : int,
            OwnerType : string,
            Owners : [{
            OwnerId : int,
            Owner : string,
            Email : string,    
            }],        
            Notes : string,
         Urls : [{
         Id : Guid,
         CredentialId : Guid,
         Url : String
         }]
       }

Request Body Details

• Max string length for Title, Description, and FileName is 256.
• Max string length for notes is 4000.
• Max string length for Url is 2048.
• Max file size is 5MB. Size must be greater than 0MB.
• Required: Title, FolderId.
• When OwnerType is set to User, then a list of Owners is required. When OwnerType is set to Group, the OwnerId is required (as the GroupId).

Response Body

[
   {
        Id : Guid,
        Title : string,
        Description : string,
        OwnerId : int,
        FolderId : Guid,
        CreatedOn : Datetime,
        CreatedBy : string,
        ModifiedOn : Datetime,
        ModifiedBy : string,
        Owner : string,
        Folder : string,
        FolderPath : string,
        Owners : [{ 
        OwnerId : int, 
        Owner : string,
        Email : string,
        }],
        OwnerType : string,
        Notes : string,
        FileName : string,
        FileHash : string,
     Urls : [{
     Id : Guid,
     CredentialId : Guid,
     Url : String
     }]          
   }
]

Response Codes

204 - No Content

400 - Bad Request

403 - Forbidden

For more information, please see Common Response Codes.

GET Secrets-Safe/Secrets

Purpose

Returns a list of secrets with the option to filter the list using query parameters.

Required Permissions

Secrets-Safe (Read).

Parameters

All parameters are optional:

• Path: the full path to the secret.
• Separator: the separator used in the path above. Default is /.
• Title: the full title of the secret.
• AfterDate: filter by modified or created on, after, or equal to the given date. Must be in the following UTC format: yyyy-MM-ddTHH:mm:ssZ.
• Limit: limit the results. Default is 1000.
• Offset: skip the first (offset) number of secrets.

Request Body

None.

Response Body

If no secrets match the specified filter parameter(s), a 200 (OK) response with an empty list is expected.

Content-Type: application/json

[ 
   {
        Id : Guid,
        Title : string,
        Description : string,
        Username : string,
        Password : string,
        OwnerId : int,
        FolderId : Guid,
        CreatedOn : Datetime,
        CreatedBy : string,
        ModifiedOn : Datetime,
        ModifiedBy : string,
        Owner : string,
        Folder : string,
        FolderPath : string,
        Owners : [{
        OwnerId : int,
        Owner : string,
        Email : string,
        }],
        OwnerType : string,
        Notes : string,
     Urls : [{
     Id : Guid,
     CredentialId : Guid,
     Url : String
     }]
    }
 ]

Response Codes

200 - OK

403 - Forbidden

For more information, please see Common Response Codes.

GET Secrets-Safe/Secrets/{secretId:guid}

Purpose

Returns a secret by ID.

Required Permissions

Secrets-Safe (Read).

Parameters

SecretId: the secret ID (GUID).

Request Body

None.

Response Body

Content-Type: application/json

[
   {
        Id : Guid,
        Title : string,
        Description : string,
        Username : string,
        Password : string,
        OwnerId : int,
        FolderId : Guid,
        CreatedOn : Datetime,
        CreatedBy : string,
        ModifiedOn : Datetime,
        ModifiedBy : string,
        Owner : string,
        Folder : string,
        FolderPath : string,
        Owners : [{
        OwnerId : int,
        Owner : string,
        Email : string,
        }],
        OwnerType : string,
        Notes : string,
     Urls : [{
     Id : Guid,
     CredentialId : Guid,
     Url : String
     }]    
   }
]

Response Codes

200 - OK

403 - Forbidden

404 - Not Found

For more information, please see Common Response Codes.

GET Secrets-Safe/Folders/{folderId:guid}/secrets

Purpose

Gets all the secrets based on the folderId.

Required Permissions

Secrets-Safe (Read).

Parameters

folderId: the given folder Id

Request Body

None.

Response Body

Content-Type: application/json

[
   {
        Id : Guid,
        Title : string,
        Description : string,
        Username : string,        
        OwnerId : int,
        FolderId : Guid,
        CreatedOn : Datetime,
        CreatedBy : string,
        ModifiedOn : Datetime,
        ModifiedBy : string,
        Owner : string,
        Folder : string,
        FolderPath : string,
        Owners : [{
        OwnerId : int,
        Owner : string,
        Email : string,
        }],
        OwnerType : string,
        Notes : string,
        FileName : string,
        FileHash : string,
     Urls : [{
     Id : Guid,
     CredentialId : Guid,
     Url : String
     }]    
   }
]

Response Codes

200 - OK

403 - Forbidden

404 - Not Found

For more information, please see Common Response Codes.

GET Secrets-Safe/Secrets/{secretId:guid}/text

Purpose

Get a secret text based on the secretId.

Required Permissions

Secrets-Safe (Read).

Parameters

SecretId: the secret id (GUID)

Request Body

None.

Response Body

Content-Type: application/json

[
   {
        Id : Guid,
        Title : string,
        Description : string,
        Text : string,
        OwnerId : int,
        FolderId : Guid,
        CreatedOn : Datetime,
        CreatedBy : string,
        ModifiedOn : Datetime,
        ModifiedBy : string,
        Owner : string,
        Folder : string,
        FolderPath : string,
        Owners : [{
        OwnerId : int,
        Owner : string,
        Email : string,
        }],
        OwnerType : string,
        Notes : string,
     Urls : [{
     Id : Guid,
     CredentialId : Guid,
     Url : String
     }]
   }
]

Response Codes

200 - OK

403 - Forbidden

404 - Not Found

For more information, please see Common Response Codes.

GET Secrets-Safe/Secrets/{secretId:guid}/file

Purpose

Gets secret file based on the secretId as file metadata with file properties. This is returned as type application/json.

Required Permissions

Secrets-Safe (Read).

Parameters

SecretId: the secret id (GUID)

Request Body

None.

Response Body

Content-Type: application/json

[
   {
        Id : Guid,
        Title : string,
        Description : string,
        OwnerId : int,
        FolderId : Guid,
        CreatedOn : Datetime,
        CreatedBy : string,
        ModifiedOn : Datetime,
        ModifiedBy : string,
        Owner : string,
        Folder : string,
        FolderPath : string,
        Owners : [{
        OwnerId : int,
        Owner : string,
        Email : string,
        }],
        OwnerType : string,
        Notes : string,
        FileName : string,
        FileHash : string,
     Urls : [{
     Id : Guid,
     CredentialId : Guid,
     Url : String
     }]    
   }
]

Response Codes

200 - OK

403 - Forbidden

404 - Not Found

For more information, please see Common Response Codes.

GET Secrets-Safe/Secrets/{secretId:guid}/file/download

Purpose

Gets secret file as an attachment based on secretId.

Required Permissions

Secrets-Safe (Read).

Parameters

SecretId: the secret id (GUID)

Request Body

None.

Response Body

Content-Type: application/octet-stream

[
   {
     FileContentResult (binary file in the response)    
   }
]

Response Codes

200 - OK

403 - Forbidden

404 - Not Found

For more information, please see Common Response Codes.

DELETE Secrets-Safe/Secrets/{secretId:guid}/

Purpose

Deletes a secret based on the secretId.

Required Permissions

Secrets-Safe (Read/Write).

Parameters

SecretId: the given secret Id (GUID)

Request Body

None.

Response Body

None.

Response Codes

200 – OK

403 - Forbidden

404 - Not found

For more information, please see Common Response Codes.