openapi: 3.1.0 info: contact: email: contact@passbolt.com description: This is a low-level overview of the API and its endpoints, if you need higher-level guides for interacting with the endpoints, use the Developer guide. license: name: AGPL-3.0 url: https://www.gnu.org/licenses/agpl-3.0.html termsOfService: https://www.passbolt.com/terms title: Passbolt Authentication (GPGAuth) Authentication (GPGAuth) Shares API version: 5.0.0 servers: - url: https://passbolt.local description: API Passbolt tags: - name: Shares description: 'Share resources and folders to users with an exhaustive permission system. ' paths: /share/{foreignModel}/{foreignId}.json: put: summary: Share a resource or folder. operationId: updateShare security: - bearerHttpAuthentication: [] x-codeSamples: - lang: cURL source: "curl --request PUT \\\n--url {{API_BASE_URL}}/share/resource/42968631-0c51-4405-9f2d-c6700c5057be.json \\\n--header 'Authorization: Bearer {{JWT_TOKEN}}' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"permissions\": [\n {\n \"id\": \"540174b9-90db-458c-ae90-e9a1912cc656\",\n \"type\": 7\n }\n ]\n}'\n" - lang: JavaScript source: "const url = '{{API_BASE_URL}}/share/resource/42968631-0c51-4405-9f2d-c6700c5057be.json';\nconst options = {\n method: 'PUT',\n headers: {Authorization: 'Bearer {{JWT_TOKEN}}'},\n body: '{\"permissions\":[{\"id\":\"540174b9-90db-458c-ae90-e9a1912cc656\",\"type\":7}]}'\n};\n\ntry {\n const response = await fetch(url, options);\n const data = await response.json();\n console.log(data);\n} catch (error) {\n console.error(error);\n}\n" - lang: PHP source: " \"{{API_BASE_URL}}/share/resource/42968631-0c51-4405-9f2d-c6700c5057be.json\",\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_ENCODING => \"\",\n CURLOPT_MAXREDIRS => 10,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,\n CURLOPT_CUSTOMREQUEST => \"PUT\",\n CURLOPT_POSTFIELDS => json_encode([\n 'permissions' => [\n [\n 'id' => '540174b9-90db-458c-ae90-e9a1912cc656',\n 'type' => 7\n ]\n ]\n ]),\n CURLOPT_HTTPHEADER => [\n \"Authorization: Bearer {{JWT_TOKEN}}\"\n ],\n]);\n\n$response = curl_exec($curl);\n$err = curl_error($curl);\n\ncurl_close($curl);\n\nif ($err) {\n echo \"cURL Error #:\" . $err;\n} else {\n echo $response;\n}\n" parameters: - $ref: '#/components/parameters/sharesForeignModel' - $ref: '#/components/parameters/foreignId' tags: - Shares requestBody: $ref: '#/components/requestBodies/shareUpdate' responses: '200': $ref: '#/components/responses/nullBody' '400': $ref: '#/components/responses/updateError' '401': $ref: '#/components/responses/authenticationRequired' '404': $ref: '#/components/responses/notFound' /share/search-aros.json: get: summary: Get AROs for sharing. operationId: indexShareAros security: - bearerHttpAuthentication: [] x-codeSamples: - lang: cURL source: "curl --request GET \\\n --url {{API_BASE_URL}}/share/search-aros.json \\\n --header 'Authorization: Bearer {{JWT_TOKEN}}'\n" - lang: JavaScript source: "const url = '{{API_BASE_URL}}/share/search-aros.json';\nconst options = {method: 'GET', headers: {Authorization: 'Bearer {{JWT_TOKEN}}'}};\n\ntry {\n const response = await fetch(url, options);\n const data = await response.json();\n console.log(data);\n} catch (error) {\n console.error(error);\n}\n" - lang: PHP source: " \"{{API_BASE_URL}}/share/search-aros.json\",\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_ENCODING => \"\",\n CURLOPT_MAXREDIRS => 10,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,\n CURLOPT_CUSTOMREQUEST => \"GET\",\n CURLOPT_HTTPHEADER => [\n \"Authorization: Bearer {{JWT_TOKEN}}\"\n ],\n]);\n\n$response = curl_exec($curl);\n$err = curl_error($curl);\n\ncurl_close($curl);\n\nif ($err) {\n echo \"cURL Error #:\" . $err;\n} else {\n echo $response;\n}\n" parameters: - $ref: '#/components/parameters/filterSearch' - $ref: '#/components/parameters/containGroupsUsers' - $ref: '#/components/parameters/containGpgkey' - $ref: '#/components/parameters/containRole' tags: - Shares responses: '200': $ref: '#/components/responses/arosIndex' '400': $ref: '#/components/responses/badRequest' '401': $ref: '#/components/responses/authenticationRequired' '404': $ref: '#/components/responses/notFound' /share/simulate/{foreignModel}/{foreignId}.json: post: summary: Simulate sharing a resource or folder. operationId: updateShareDryRun security: - bearerHttpAuthentication: [] x-codeSamples: - lang: cURL source: "curl --request POST \\\n\n --url {{API_BASE_URL}}/share/simulate/resource/42968631-0c51-4405-9f2d-c6700c5057be.json \\\n --header 'Authorization: Bearer {{JWT_TOKEN}}' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"permissions\": [\n {\n \"id\": \"540174b9-90db-458c-ae90-e9a1912cc656\",\n \"delete\": true\n }\n ]\n }'\n" - lang: JavaScript source: "const url = '{{API_BASE_URL}}/share/simulate/resource/42968631-0c51-4405-9f2d-c6700c5057be.json';\nconst options = {\n method: 'POST',\n headers: {Authorization: 'Bearer {{JWT_TOKEN}}'},\n body: '{\"permissions\":[{\"id\":\"540174b9-90db-458c-ae90-e9a1912cc656\",\"delete\":true}]}'\n};\n\ntry {\n const response = await fetch(url, options);\n const data = await response.json();\n console.log(data);\n} catch (error) {\n console.error(error);\n}\n" - lang: PHP source: " \"{{API_BASE_URL}}/share/simulate/resource/42968631-0c51-4405-9f2d-c6700c5057be.json\",\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_ENCODING => \"\",\n CURLOPT_MAXREDIRS => 10,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,\n CURLOPT_CUSTOMREQUEST => \"POST\",\n CURLOPT_POSTFIELDS => json_encode([\n 'permissions' => [\n [\n 'id' => '540174b9-90db-458c-ae90-e9a1912cc656',\n 'delete' => True\n ]\n ]\n ]),\n CURLOPT_HTTPHEADER => [\n \"Authorization: Bearer {{JWT_TOKEN}}\"\n ],\n]);\n\n$response = curl_exec($curl);\n$err = curl_error($curl);\n\ncurl_close($curl);\n\nif ($err) {\n echo \"cURL Error #:\" . $err;\n} else {\n echo $response;\n}\n" parameters: - $ref: '#/components/parameters/sharesForeignModel' - $ref: '#/components/parameters/foreignId' tags: - Shares requestBody: $ref: '#/components/requestBodies/shareUpdateDryRun' responses: '200': $ref: '#/components/responses/updateDryRun' '400': $ref: '#/components/responses/updateError' '401': $ref: '#/components/responses/authenticationRequired' '404': $ref: '#/components/responses/notFound' components: schemas: groupsUsersIndexAndView: type: object required: - id - group_id - user_id - is_admin - created properties: id: type: string format: uuid group_id: type: string format: uuid user_id: type: string format: uuid is_admin: type: boolean created: type: string format: date-time user: $ref: '#/components/schemas/userIndexAndView' shareUpdateError: type: object properties: permissions: type: array items: type: object properties: aco_forein_key: type: object properties: permission_unique: type: string aco_exists: type: string _existsIn: type: string aro_forein_key: type: object properties: aro_exists: type: string _existsIn: type: string shareUpdate: type: object properties: permissions: type: array items: $ref: '#/components/schemas/permissionUpdate' secrets: description: Not required on simulation. type: array items: $ref: '#/components/schemas/secretAdd' permissionUpdate: type: object properties: id: type: string format: uuid aro: type: string enum: - User - Group aro_foreign_key: type: string format: uuid type: $ref: '#/components/schemas/permissionLevel' delete: type: boolean is_new: type: boolean userIndexAndView: type: object required: - id - role_id - username - active - deleted - created - modified - disabled properties: is_mfa_enabled: type: boolean id: type: string format: uuid role_id: type: string format: uuid username: type: string active: type: boolean deleted: type: boolean created: type: string format: date-time modified: type: string format: date-time disabled: type: string format: date-time x-nullable: true profile: type: object required: - id - user_id - first_name - last_name - created - modified - avatar properties: id: type: string format: uuid user_id: type: string format: uuid first_name: type: string last_name: type: string created: type: string format: date-time modified: type: string format: date-time avatar: type: object required: - url properties: id: type: string format: uuid profile_id: type: string format: uuid created: type: string format: date-time modified: type: string format: date-time url: type: object required: - medium - small properties: medium: type: string format: url small: type: string format: url groups_users: $ref: '#/components/schemas/groupsUsersIndexAndView' gpgkey: $ref: '#/components/schemas/gpgkey' x-nullable: true role: $ref: '#/components/schemas/role' missing_metadata_key_ids: type: array items: type: string format: uuid last_logged_in: type: string format: date-time x-nullable: true groupIndexAndView: type: object required: - id - name - deleted - created - modified - created_by - modified_by properties: id: type: string format: uuid name: type: string deleted: type: boolean created: type: string format: date-time modified: type: string format: date-time created_by: type: string format: uuid modified_by: type: string format: uuid my_group_user: $ref: '#/components/schemas/groupsUsersIndexAndView' groups_users: type: array items: $ref: '#/components/schemas/groupsUsersIndexAndView' user_count: type: integer shareUpdateDryRun: type: object required: - added - removed properties: added: type: array items: type: object properties: User: type: object properties: id: type: string format: uuid removed: type: array items: type: object properties: User: type: object properties: id: type: string format: uuid secretAdd: type: object required: - data properties: user_id: type: string format: uuid data: type: string resource_id: type: string format: uuid shareAros: oneOf: - $ref: '#/components/schemas/userIndexAndView' - $ref: '#/components/schemas/groupIndexAndView' gpgkey: type: object required: - id - user_id - armored_key - bits - uid - key_id - fingerprint - type - expires - key_created - deleted - created - modified properties: id: type: string format: uuid user_id: type: string format: uuid armored_key: type: string bits: type: integer uid: type: string key_id: type: string fingerprint: type: string type: type: string enum: - RSA - ECC expires: type: string format: date-time x-nullable: true deleted: type: boolean created: type: string format: date-time modified: type: string format: date-time permissionLevel: description: '* `1` - Read * `7` - Update * `15` - Owner ' type: integer enum: - 1 - 7 - 15 role: type: object required: - id - name - description - created - modified properties: id: type: string format: uuid name: type: string enum: - admin - guest - user description: type: string created: type: string format: date-time modified: type: string format: date-time header: type: object required: - id - status - servertime - action - message - url - code properties: id: type: string format: uuid status: type: string enum: - success - error servertime: type: integer example: 1720702619 action: type: string format: uuid message: type: string example: The operation was successful. url: type: string format: uri example: /auth/verify.json code: type: integer example: 200 responses: nullBody: description: Operation is successful. content: application/json: schema: type: object required: - header - body properties: header: $ref: '#/components/schemas/header' body: type: 'null' examples: base: value: header: id: f7be85c0-afb1-4d8e-a9e1-e05abb0bb71a status: success servertime: 1721727753 action: e2aa01a9-84ec-55f8-aaed-24ee23259339 message: url: code: 200 body: null arosIndex: description: Operation is successful content: application/json: schema: type: object required: - header - body properties: header: $ref: '#/components/schemas/header' body: type: array items: $ref: '#/components/schemas/shareAros' examples: base: value: header: id: 7ff2828c-1092-4897-8e0a-1dc64ada889f status: success servertime: 1721207029 action: 4d0c0996-ce30-4bce-9918-9062ab35c542 message: The operation was successful. url: /share/search-aros.json code: 200 body: - id: c48863da-32d3-48cd-9d47-de2891386423 role_id: c2f96fb1-611d-466d-80fb-e82beba5ed87 username: ada@passbolt.com active: true deleted: false created: '2024-08-08T12:08:58+00:00' modified: '2024-08-08T12:14:38+00:00' disabled: null groups_users: - id: 95accfa0-5c2c-47af-ba63-dd9efb46f99b group_id: 8fa37ef6-f167-4342-8e1c-3488439cf7d1 user_id: c48863da-32d3-48cd-9d47-de2891386423 is_admin: false created: '2024-08-08T12:25:40+00:00' profile: id: 4d9e9297-b1ec-4aa1-af1c-c6693c3ffe36 user_id: c48863da-32d3-48cd-9d47-de2891386423 first_name: Ada last_name: Lovelace created: '2024-08-08T12:08:58+00:00' modified: '2024-08-08T12:08:58+00:00' avatar: url: medium: https://passbolt.local/img/avatar/user_medium.png small: https://passbolt.local/img/avatar/user.png gpgkey: id: 6f0f6eb6-ed74-4cb0-8872-3e96ee17b6f9 user_id: c48863da-32d3-48cd-9d47-de2891386423 armored_key: '-----BEGIN PGP PUBLIC KEY BLOCK-----' bits: 3072 uid: Ada Lovelace key_id: 08EF12596BC6B07B fingerprint: C4D0E64738F9956CDACC6D4808EF12596BC6B07B type: RSA expires: null key_created: '2024-08-08T12:13:42+00:00' deleted: false created: '2024-08-08T12:14:38+00:00' modified: '2024-08-08T12:14:38+00:00' role: id: c2f96fb1-611d-466d-80fb-e82beba5ed87 name: user description: Logged in user created: '2012-07-04T13:39:25+00:00' modified: '2012-07-04T13:39:25+00:00' last_logged_in: null - user_count: 1 id: 8fa37ef6-f167-4342-8e1c-3488439cf7d1 name: Groupe B deleted: false created: '2024-07-22T16:01:07+00:00' modified: '2024-07-22T16:01:07+00:00' created_by: 8bb80df5-700c-48ce-b568-85a60fc3c8f2 modified_by: 8bb80df5-700c-48ce-b568-85a60fc3c8f2 authenticationRequired: description: Authentication required. content: application/json: schema: type: object required: - header - body properties: header: $ref: '#/components/schemas/header' body: type: string examples: base: value: header: id: f7be85c0-afb1-4d8e-a9e1-e05abb0bb71a status: error servertime: 1721727753 action: e2aa01a9-84ec-55f8-aaed-24ee23259339 message: Authentication is required to continue. url: code: 401 body: '' badRequest: description: Bad request content: application/json: schema: type: object required: - header - body properties: header: $ref: '#/components/schemas/header' body: type: string examples: example: value: header: id: 7ff2828c-1092-4897-8e0a-1dc64ada889f status: error servertime: 1721207029 action: 4d0c0996-ce30-4bce-9918-9062ab35c542 message: url: code: 400 body: '' updateDryRun: description: Operation is successful content: application/json: schema: type: object required: - header - body properties: header: $ref: '#/components/schemas/header' body: $ref: '#/components/schemas/shareUpdateDryRun' examples: base: value: header: id: 7ff2828c-1092-4897-8e0a-1dc64ada889f status: success servertime: 1721207029 action: 4d0c0996-ce30-4bce-9918-9062ab35c542 message: The operation was successful. url: /share/simulate/resource/42968631-0c51-4405-9f2d-c6700c5057be.json code: 200 body: changes: added: [] removed: - User: id: c48863da-32d3-48cd-9d47-de2891386423 notFound: description: Not found content: application/json: schema: type: object required: - header - body properties: header: $ref: '#/components/schemas/header' body: type: string examples: example: value: header: id: 7ff2828c-1092-4897-8e0a-1dc64ada889f status: error servertime: 1721207029 action: 4d0c0996-ce30-4bce-9918-9062ab35c542 message: The does not exist. url: code: 404 body: '' updateError: description: Bad request content: application/json: schema: type: object required: - header - body properties: header: $ref: '#/components/schemas/header' body: $ref: '#/components/schemas/shareUpdateError' examples: base: value: header: id: 7ff2828c-1092-4897-8e0a-1dc64ada889f status: success servertime: 1721207029 action: 4d0c0996-ce30-4bce-9918-9062ab35c542 message: Resource metadata key type is invalid. url: /share/resource/42968631-0c51-4405-9f2d-c6700c5057be.json code: 400 body: permissions: aco_foreign_key: permission_unique: A permission already exists for the given access control object and access request object. parameters: containRole: name: contain[role] description: Add role to response body. in: query required: false schema: type: integer enum: - 1 - 0 containGpgkey: name: contain[gpgkey] description: Add GPG key data to response body. in: query required: false schema: type: integer enum: - 1 - 0 foreignId: name: foreignId description: ID for the foreign element being manipulated. in: path required: true schema: type: string format: uuid sharesForeignModel: name: foreignModel description: Type for the foreign model being shared. in: path required: true schema: type: string enum: - resource - folder containGroupsUsers: name: contain[groups_users] description: Add group users to groups in response body. in: query required: false schema: type: integer enum: - 1 - 0 filterSearch: name: filter[search] description: Filter using a keyword or a string. in: query required: false schema: type: string requestBodies: shareUpdate: description: The permissions you want to apply required: true content: application/json: schema: $ref: '#/components/schemas/shareUpdate' examples: addUser: summary: Adding a read permission for a user value: permissions: - aro: User aro_foreign_key: c48863da-32d3-48cd-9d47-de2891386423 type: 1 is_new: true secrets: - data: '-----BEGIN PGP MESSAGE-----' user_id: c48863da-32d3-48cd-9d47-de2891386423 deleteUser: summary: Removing a permission for a user value: permissions: - aro: User aro_foreign_key: c48863da-32d3-48cd-9d47-de2891386423 delete: true secrets: [] updatePermissionLevel: summary: Update a permission level value: permissions: - id: 540174b9-90db-458c-ae90-e9a1912cc656 type: 7 everythingAtOnce: summary: Multiple operations at the same time value: permissions: - aro: User aro_foreign_key: c48863da-32d3-48cd-9d47-de2891386423 type: 1 is_new: true - id: 540174b9-90db-458c-ae90-e9a1912cc656 type: 7 secrets: - data: '-----BEGIN PGP MESSAGE-----' user_id: c48863da-32d3-48cd-9d47-de2891386423 shareUpdateDryRun: description: The permissions you want to apply required: true content: application/json: schema: $ref: '#/components/schemas/shareUpdate' examples: deleteUser: value: permissions: - id: 540174b9-90db-458c-ae90-e9a1912cc656 delete: true securitySchemes: bearerHttpAuthentication: description: Bearer token using a JWT type: http scheme: Bearer bearerFormat: JWT gpgCookieAuthentication: description: Session-based authentication. Note that a CSRF token needs to be provided through a header named `X-CSRF-Token`. type: apiKey in: cookie name: passbolt_session