Secrets Safe APIs

This document specifies the Representational State Transfer (REST) compliant Application Programmer Interface (API) over HTTPS for BeyondInsight and Password Safe. It is a way to integrate a portion of the BeyondInsight and Password Safe functionality into your own applications.

Using the REST API makes it easier for users to build customized solutions for their specific needs while ensuring secure data transmission. The API provides a set of predefined operations, or endpoints, that can be accessed using HTTP Requests, including GET requests to retrieve data, POST requests to create new data, PUT requests to update existing data, and DELETE requests to remove data.

This resource is intended for readers with knowledge of HTTPS request and response processing, web development, and JSON notation.

Folders

ℹ️
Note
In BeyondInsight/Password Safe 24.3, "UserGroupId" has been deprecated.

POST Secrets-Safe/Folders/

Purpose

Creates a new Secrets Safe folder for the given user group.

Required permissions

Secrets-Safe (Read/Write).

Request body

Content-Type: application/json

{
    Name: string,
    Description: string,
    ParentId: Guid,
    UserGroupId: int,
}

Request body details

Max string length for description is 256.

Response body

Content-Type: application/json

{
    Id: Guid,
    Name: string,
    Description: string,
    ParentId: Guid,
    UserGroupId: int,
}

Response codes

201 - Request successful. Secrets Safe Folder in the response body.
409 - Conflict.

POST Secrets-Safe/Folders/{id}

Purpose

Imports a CSV secrets file into the specified folder.

Required permissions

Workforce Passwords Read/Write, when destination folder is a Personal Folder.
Workforce Passwords Read/Write and Secrets Safe ReadWrite, when destination folder is a team folder.

Parameters

folderid: the folder ID (GUID).

Request body

Content-Type: multipart/form-data

Response body

{
    totalNumber: int,
    errors: [ {
      lineNumber: int,
      error: string
     }
    ],
    successfulImport: int
   }

TotalNumber: Number of credentials processed. Includes failures.
Errors: List of errors. Includes the error message and CSV line number
SuccessfulImport: Number of credentials successfully imported.

Response codes

201 – Request partially or completely successful. Refer to errors and successfulImport values in response body.

GET Secrets-Safe/Folders/

Purpose

Returns a list of Secrets Safe folders to which the current user has access.

Required permissions

Secrets-Safe (Read).

Parameters

To filter the results, use any combination of the following:

FolderName: The partial name of the folder.
FolderPath: Child folders are also included. Separator is /.
IncludeSubfolders: Indicate whether to include the subfolder. Default is true.
RootOnly: The results only include those folders at the root level.
FolderOwnerId: Filter results by the folders which are owned by the given FolderOwnerId.
Limit: Limits the results by the given integer greater than 0. Default is 1000.
Offset: Skip the first (offset) number of secrets.

Request body

None.

Response body

Content-Type: application/json

[{
    Id: Guid,
    Name: string,
    Description: string,
    ParentId: Guid,
    UserGroupId: int,
},
…
]

Response codes

200 - Request successful. Secrets Safe Folders in the response body.

PUT Secrets-Safe/Folders/{id}

Purpose

Updates a Secrets Safe folder by ID.

Required permissions

Secrets-Safe (Read/Write).

Parameters

id: the folder ID (GUID).

Request body

Content-Type: application/json

{
    Name: string,
    Description: string,
    ParentId: Guid,
    UserGroupId: int,
}

Request body details

Max string length for description is 256.

Response body

Content-Type: application/json

[{
    Id: Guid,
    Name: string,
    Description: string,
    ParentId: Guid,
    UserGroupId: int,
},
…
]

Response codes

200 - Request successful. Secrets Safe Folders in the response body.

DELETE Secrets-Safe/Folders/{id}

Purpose

Deletes a Secrets Safe folder by ID.

Required permissions

Secrets-Safe (Read/Write).

ℹ️
Note
Folders that contain secrets cannot be deleted.

Parameters

id: the folder ID (GUID).

Request body

None.

Response body

None.

Response codes

200 - Request successful. Secrets Safe folders in the response body.

GET Secrets-Safe/Folders/{id}

Purpose

Returns a Secrets Safe folder by ID.

Required permissions

Secrets-Safe (Read).

Parameters

id: the folder ID (GUID).

Request body

None.

Response body

Content-Type: application/json

{
    Id: Guid,
    Name: string,
    Description: string,
    ParentId: Guid,
    UserGroupId: int,
}

Response codes

200 - Request successful. Secrets Safe Folder in the response body.

Secrets

ℹ️
Note

In BeyondInsight/Password Safe 24.3, "OwnerId" and "OwnerType" have been deprecated. New parameters from "Owners" are used instead.

API version 3.0 is the default, however 3.1 is recommended version.

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

Request body (version 3.0)

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 (version 3.1)

Content-Type: application/json

{
         Title : string,
         Description : string,
         Username : string,
         Password : string,
         Owners : [{ 
            GroupId : int,
            UserId : int, 
            Name : 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

Response body (Version 3.0)

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 body (Version 3.1)

Content-Type: application/json

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

Response codes

201 - Created

400 - Bad Request

403 - Forbidden

409 - Conflict

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

Request body (version 3.0)

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 (version 3.1)

Content-Type: application/json

{
            Title : string,
            Description : string,
            Text : string,
            Owners : [{ 
               GroupId : int, 
               UserId : int,
               Name :  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

Response body (version 3.0)

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 body (version 3.1)

Content-Type: application/json

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

Response codes

201 - Created

400 - Bad Request

403 - Forbidden

409 - Conflict.

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

Request body (version 3.0)

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 (version 3.1)

Content-Type: multipart/form-data

{
            Title : string,
            Description : string,
            Owners : [{ 
              GroupId : int,
              UserId : int,
              Name :  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

Response body (version 3.0)

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 body (version 3.1)

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,
     FolderId : Guid,
     CreatedOn : Datetime,
     CreatedBy : string,
     ModifiedOn : Datetime,
     ModifiedBy : string,
     Folder : string,
     FolderPath : string,
     Owners : [{ 
        GroupId : int,
        UserId : int,
        Name :  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

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

Request body (version 3.0)

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 (version 3.1)

Content-Type: application/json

{
    FolderId : Guid,
    Title : string,
    Description : string,
    Username : string,
    Password : string,
    Owners : [{
        GroupId : int,
        UserId : int,
        Name :  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, 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).
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

Response body (version 3.0)

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,
        Urls : [{
          Id : Guid,
          CredentialId : Guid,
          Url : String
     }]
  }

Response body (version 3.1)

Content-Type: application/json

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

Response codes

204 - No Content

403 - Forbidden

400 - Bad Request

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

Request body (version 3.0)

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 (version 3.1)

Content-Type: application/json

{
    FolderId : Guid,
    Title : string,
    Description : string,
    Owners : [{
        GroupId : int,
        UserId : int,
        Name :  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

Response body (version 3.0)

{
    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 body (version 3.1)

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

Response codes

204 - No Content

400 - Bad Request

403 - Forbidden

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

Request body (version 3.0)

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 (version 3.1)

Content-Type: application/json

{
    FolderId : Guid,
    Title : string,
    Description : string,
    Owners : [{
        GroupId : int,
        UserId : int,
        Name :  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

Response body (version 3.0)

{
      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 body (version 3.1)

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

Response codes

204 - No Content

400 - Bad Request

403 - Forbidden

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

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

Response body (version 3.0)

Content-Type: application/json

[ 
   {
        Id : Guid,
        Title : string,
        Description : string,
        Username : string,
        Password : string,
		    FileName: string,
        FileHash: string,
        Text: String,
        SecretType: Int,
        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 body (version 3.1)

Content-Type: application/json

[ 
   {
        Id : Guid,
        Title : string,
        Description : string,
        Username : string,
        Password : string,
        FileName: string,	
	      FileHash: string,	
	      Text: String,
	      SecretType: Int,
        FolderId : Guid,
        CreatedOn : Datetime,
        CreatedBy : string,
        ModifiedOn : Datetime,
        ModifiedBy : string,
        Folder : string,
        FolderPath : string,
        Owners : [{
            GroupId : int,
            UserId : int,
			      Name :  string,
            Email : string,
        }],
        Notes : string,
        Urls : [{
            Id : Guid,
            CredentialId : Guid,
            Url : String
     }]
    }
 ]

Response codes

200 - OK

403 - Forbidden

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

Response body (version 3.0)

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 body (version 3.1)

Content-Type: application/json

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

Response codes

200 - OK

403 - Forbidden

404 - Not Found

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

Response body (version 3.0)

Content-Type: application/json

{
      Id : Guid,
      Title : string,
      Description : string,
      Username : string,
      Password: string,
      Text: String,
      SecretType:int,      
      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 body (version 3.1)

Content-Type: application/json

{
        Id : Guid,
        Title : string,
        Description : string,
        Username : string,
        Password: string,
        FileName : string,
        FileHash : string,
        Text: String,
	      SecretType:int,        
        FolderId : Guid,
        CreatedOn : Datetime,
        CreatedBy : string,
        ModifiedOn : Datetime,
        ModifiedBy : string,
        Folder : string,
        FolderPath : string,
        Owners : [{
            GroupId : int,
            UserId : int,
			      Name :  string,
            Email : string,
        }],
        Notes : string,
        Urls : [{
            Id : Guid,
            CredentialId : Guid,
            Url : String
     }]    
  }

Response codes

200 - OK

403 - Forbidden

404 - Not Found

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

Response body (version 3.0)

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 body (version 3.1)

Content-Type: application/json

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

Response codes

200 - OK

403 - Forbidden

404 - Not Found

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

Response body (version 3.0)

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 body (version 3.1)

Content-Type: application/json

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

Response codes

200 - OK

403 - Forbidden

404 - Not Found

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

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

POST secrets-safe/secrets/{secret-id}/shares/{folder-id}/

Purpose

Creates a shared secret in a folder.

Parameters

secret-id: the secret Id (GUID)

folder-id: the folder ID (GUID)

Request body

None.

Response body

 {
     SecretId : Guid,
     FolderID : Guid,
     FolderPath : string,
     SecretName : string
  }

Response codes

201 – OK

404 – Not found

GET secrets-safe/secrets/{secret-id}/shares

Purpose

Fetches all shared secrets for a given secret.

Required permissions

Secrets Safe (Read).

Parameters

secret-id: the secret Id (GUID)

Request body

None.

Response body

 {
     SecretId : Guid,
     FolderID : Guid,
     FolderPath : string,
     SecretName : string
  }

Response codes

200 – OK

404 – Not found

DELETE secrets-safe/secrets/{secret-id}/shares/{folder-id}

Purpose

Removes a shared secret from a folder.

Required permissions

Secrets Safe (Read).

Parameters

secret-id: the secret Id (GUID)

folder-id: the folder ID (GUID)

Request body

None.

Response body

None.

Response codes

204 – OK

404 – Not found

DELETE secrets-safe/secrets/{secret-id}/shares

Purpose

Removes all shared secrets for a given secret.

Required permissions

Secrets Safe (Read).

Parameters

secret-id: the secret Id (GUID)

Request body

None.

Response body

None.

Response codes

204 – OK

404 – Not found

POST secrets-safe/safes

Purpose

Creates a new safe.

Required permissions

Secrets Safe (Read/Write).

Parameters

None.

Request body

 {
     Name: string,
     Description: string
  }

Request body details

Name: (required) string . Max string length is 256.

Description: (optional) string. Max string length is 256.

Response body

{  
     Id : Guid,   
     Name: string,
     SecretName : string,
     PermissionFlags: [
     "Read",
     "Create",
     "Edit",
     "Delete",
     "Manage",
     "Share" ]
}

Response codes

201 – OK

409 – Name already exists

GET secrets-safe/safes

Purpose

Returns all safes.

Required permissions

Secrets Safe (Read).

Parameters

None.

Request body

None.

Response body

{  
     Id : Guid,   
     Name: string,
     SecretName : string
}

Response codes

201 – OK

GET secrets-safe/safes/{id}

Purpose

Returns a safe by ID.

Required permissions

Secrets Safe (Read).

Parameters

id: the safe ID (GUID).

Request body

None.

Response body

{  
     Id : Guid,   
     Name: string,
     SecretName : string
}

Response codes

200 – OK

400 – Subfolder ID used

404 – Safe does not exist

PUT secrets-safe/safes/{id}

Purpose

Updates a safe by ID.

Required permissions

Secrets Safe (Read).

Parameters

id: the safe ID (GUID).

Request body

 {
     Name: string,
     SecretName : string
  }

Request body details

Name: (required) string . Max string length is 256.

SecretName: (optional) string. Max string length is 256.

Response body

None.

Response codes

204 – OK

400 – Subfolder ID used

404 – Safe does not exist

409 – Name already exists

DELETE secrets-safe/safes/{id}

Purpose

Deletes a safe by ID.

Required permissions

Secrets Safe (Read/Write).

Parameters

id: the safe ID (GUID)

Request body

None.

Response body

None.

Response codes

204 – OK

400 – Safe does not exist

404 – Not found

GET secrets-safe/safes/{id}/safe-permissions

Purpose

Returns the safe permissions by ID.

Required permissions

Secrets Safe (Read).

Parameters

id: the safe ID (GUID)

Request body

None.

Response body

{  
     Id : Guid,   
     FolderId: Guid,
     GroupId : integer,
     UserId : integer, 
     PermissionFlags: [
     "Read",
     .
     .
            ]
     ExpiresOn : datetime
}

Response codes

200 – OK

400 – Unauthorized to list permissions

PUT secrets-safe/safes/{id}/safe-permissions

Purpose

Assigns safe permissions by ID.

Required permissions

Secrets Safe (Read).

Parameters

id: the safe ID (GUID).

Request body

{  
     PrincipalType : integer,
     PrincipalID: integer,
     PermissionFlags: [
     .
     .
     .
            ]
     ExpiresOn : null
}

Request body details

PrincipalType : (required) integer. 0 for user, 1 for group.
PrincipalID: (required) integer. ID of the user or group.
PermissionFlags: The effective permissions to assign.
- These are the list of possible permissions combination that can be assigned.
  - Permissions :
    "None",
    "Read",
    "Read, Create",
    "Read, Update",
    "Read, Create, Update",
    "Read, Delete",
    "Read, Create, Delete",
    "Read, Update, Delete",
    "Read, Create, Update, Delete",
    "Read, Share",
    "Read, Create, Share",
    "Read, Update, Share",
    "Read, Create, Update, Share",
    "Read, Delete, Share",
    "Read, Create, Delete, Share",
    "Read, Update, Delete, Share",
    "Read, Create, Update, Delete, Share",
    "Manage Safe"
ExpiresOn: (optional) datetime.

Response body

None.

Response codes

204 – OK

403 - Unauthorized to edit permissions

DELETE secrets-safe/safes/{id}/safe-permissions

Purpose

Revokes safe permissions by ID.

Required permissions

Secrets Safe (Read).

Parameters

id: the safe ID (GUID).

Request body

 {
     PrincipalType : integer,
     PrincipalID: integer
  }

Request body details

PrincipalType : (required) integer. 0 for user, 1 for group.

PrincipalID: (required) integer. ID of the user or group.

Response body

None.

Response codes

204 – OK

403 - Unauthorized to edit permissions

GET secrets-safe/safes/safe-permissions

Purpose

Returns the set of possible safe permissions.

Required permissions

Secrets Safe (Read).

Parameters

None.

Request body

None.

Response body

{  
   "None",  
   "Read",  
   "Create",  
   "Edit",  
   "Delete",  
   "Manage",  
   "Share"  
}

Response codes

200 – OK

Folders

ℹ️Note

POST Secrets-Safe/Folders/

Purpose

Required permissions

Request body

Request body details

Response body

Response codes

POST Secrets-Safe/Folders/{id}

Purpose

Required permissions

Parameters

Request body

Response body

Response codes

GET Secrets-Safe/Folders/

Purpose

Required permissions

Parameters

Request body

Response body

Response codes

PUT Secrets-Safe/Folders/{id}

Purpose

Required permissions

Parameters

Request body

Request body details

Response body

Response codes

DELETE Secrets-Safe/Folders/{id}

Purpose

Required permissions

ℹ️Note

Parameters

Request body

Response body

Response codes

GET Secrets-Safe/Folders/{id}

Purpose

Required permissions

Parameters

Request body

Response body

Response codes

Secrets

ℹ️Note

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

Purpose

Required permissions

Parameters

Request body

Request body details

Response body

Response codes

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

Purpose

Required permissions

Parameters

Request body

Request body details

Response body

Response codes

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

Purpose

Required permissions

Parameters

Request body

Request body details

Response body

Response codes

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

Purpose

Required permissions

Parameters

Request body

Request body details

Response body

Response codes

ℹ️
Note

ℹ️
Note

ℹ️
Note

ℹ️
Note