Passbolt Shares API
Share resources and folders to users with an exhaustive permission system.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/passbolt-shares-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
OpenAPI Specification
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: "<?php\n$curl = curl_init();\n\ncurl_setopt_array($curl, [\n CURLOPT_URL => \"{{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: "<?php\n$curl = curl_init();\n\ncurl_setopt_array($curl, [\n CURLOPT_URL => \"{{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: "<?php\n$curl = curl_init();\n\ncurl_setopt_array($curl, [\n CURLOPT_URL => \"{{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: <SUCCESS MESSAGE>
url: <API ENDPOINT 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 <ada@passbolt.com>
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: <API ENDPOINT 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: <ERROR MESSAGE>
url: <API ENDPOINT 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 <MODEL> does not exist.
url: <API ENDPOINT 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