How to use the Share API in ioGates to manage Share URLs, including retrieving share information, creating new shares, updating existing shares, and deleting shares, with detailed guidelines on authorization, request, and response formats.
The Share API enables information to be obtained for a ShareLink.
Get Share Info
Share objects can be retrieved with a share token or using the share ID along with a user token for the owner of the share.
URL: /api/share[/id]
Method: Get
Request Headers
Authorisation: A Bearer token is required, which is obtained from the auth token API.
Example:
Authorisation: Bearer 123-BodrEJHrC43KejPcM0nzTl05gUMi3i8ruzGN
Response Body
The response body is a JSON-formatted representation of the share.
| id | The share id. |
| name | The name of the share. |
| expired | Boolean. Whether or not the share has expired. |
| expires | String or null. The expiry date of the share. If null the share never expires. |
| owner | User profile for the owner of the share. Object contains: id, username, realname, accountname, email, address, mobile, expires, and status. Status may be: Active, Inactive, Blocked, or ValidationRequired. |
| user | User profile for the receiver of the share. |
| permissions |
Contains the permission for the share (all boolean):
|
| file id | The ID of the shared file or folder |
| type | File type: dir or file |
| two_factor | Whether or not Two Factor auth is required. See Two Factor Auth API. |
| URL | The share URL. Null if user is not the owner of the share. |
| email_status | If you share an email, this contains an object with delivery information. The object contains status, timestamp, and message. |
| max_file_size |
Integer. Max allowed upload file size in bytes. 0 means no limit. |
| available_storage | Integer. Storage left on account in bytes. |
Create Share
URL: /api/share
Method: POST
Request Headers
Authorisation: A Bearer token is required, which is obtained from the auth token API.
Example:
Authorisation: Bearer 123-BodrEJHrC43KejPcM0nzTl05gUMi3i8ruzGN
Response Body
The response body is a JSON-formatted representation of the share.
| receiver |
Email to send the share. It may be a list of email addresses separated by a comma. If non-email share, this may be used to set the name of the share. |
| file_id | The file or folder ID to share. |
| subject | Email subject. |
| message | Email message. |
| expires | Share expiry. Possible values: - null (no expiry) - Date/time specification (ISO8601 or ATOM) - Relative time ("+5 days", "+1 week", "tomorrow", etc) |
| Boolean. Specify if the share is an email share or a URL share. Default true | |
| permissions |
Object. Contains the permission for the share (all boolean):
Note: Limitations/configurations on the account may force permissions to specific values. |
| return_url_share |
Boolean, default true. If set to false and the email is true, the return share will be the created share. If multiple receivers, only the first share will be returned. If true, the returned share will be a non-email share, which can be used for manual distribution. |
| type | File type: dir or file |
| two_factor | Whether or not Two Factor auth is required. See Two Factor Auth API. |
| URL | The share URL. Null if user is not the owner of the share. |
| email_status | If you share an email, this contains an object with delivery information. The object contains status, timestamp, and message. |
| max_file_size |
Integer. Max allowed upload file size in bytes. 0 means no limit. |
| available_storage | Integer. Storage left on account in bytes. |
Response Body
URL: /api/share/[id]
Method: PUT
Use the same request body as in POST but may only include values to update.
Delete Share
URL: /api/share/[id]
Method: DELETE
Response code will be 204 if success.