> For the complete documentation index, see [llms.txt](https://docs.tiny.plus/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tiny.plus/api/concepts/permissions.md). # Permissions and confidential records ## A token acts as a person Every request is made as the person the token belongs to. It sees what they can see in tiny+, and changes only what they may change. Records it creates are theirs. Only account admins can set `created_user` or `modified_user` to someone else, to create or change a record on their behalf. Only account admins can set `created_date` or `modified_date`. Anyone else who sends one of these gets a `403`, unless the value is their own id or the value the record already has: ```javascript { "error": "Only an account admin can create a record on someone else's behalf (created_user)." } ``` ## Changing and deleting records Every record in a response carries two flags for the token's user: * `perm_edit`: whether they may change it; * `perm_delete`: whether they may delete it. For projects, companies, contacts and most other record types, a record can be changed and deleted by: * the person who created it; * the person it's assigned to; * the members of its team; * anyone with the Records Admin role. Account admins have it too. Posts can be changed and deleted by their author and by anyone with the News Feed Admin role. Account admins have it too. Changing or deleting a record the token's user may not change fails with `403`: ```javascript { "error": "You may not edit this record: it is not one you own or administer." } ``` ## Read-only tokens A ReadOnly [simple access token](/api/getting-access/getting-an-access-token.md), or an OAuth token granted only the `read` scope, can't change anything. Most of the API doesn't refuse its writes up front, so check the response: | Request | Response | | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | `POST /v2/{type}` | `400` `{"error": "Could not add record. - 26"}` | | `PATCH` or `DELETE /v2/{type}/{id}` | `200` `{"results": false}` | | [`POST /v2/attachments`](/api/endpoints/attachments.md) | `403` `{"error": "This token is read-only."}` | | `POST` or `PATCH` to [`/v2/relationship_plans`](/api/endpoints/relationship-plans.md) | `403` `{"error": "This connection is read-only, so nothing can be changed."}` | | `POST`, `PATCH` or `DELETE` to [`/v2/bid_teams`](/api/endpoints/bid-teams.md) | `403` `{"error": "This token is read-only."}` | ## Confidential records A record can be marked confidential. Only these people can see a confidential record: * its team members and subscribers; * the person who created it, and the person it's assigned to; * anyone with the Records Admin role, including account admins. For anyone else, the API behaves as if the record were hidden: | Request | Result | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Lists and search | The record is left out, and not counted in `total_records`. | | Getting the record | A masked copy with little more than its id: the name reads "(Confidential project)", and `show_obscured` is `true`. | | Its change history, [status pipeline](/api/endpoints/projects.md#status-pipeline) or [images and documents](/api/endpoints/attachments.md#images-and-documents-on-a-record) | `403` `{"error": "This record is confidential."}` | | A link to one of its documents | `404`, unless the document is also on a record they can see. | | Posts about it | An empty list. | | Another record's `related` | The record is left out. | | Its [bid teams](/api/endpoints/bid-teams.md) | `404`, as if it had none, and they're left out of a lead firm's teams. A confidential lead firm or contact on a team reads "(Confidential company)" or "(Confidential contact)". | | A project or contact linked to a confidential company | `primary_company_name` and `primary_company_id_name` read "(Confidential company)". A contact's `primary_company_record_status` and `primary_company_record_phase` come back empty. | | Changing it | `403`. | | Joining its team | `403`. Someone on the team has to add them. | Every record the API returns has `show_obscured`, which is `true` when the record has been masked. {% hint style="info" %} List pages of more than 50 records don't load teams or subscribers. On those pages, a confidential record that someone can see only as a team member or subscriber may come back masked. Ask for 50 records or fewer to get it in full. A confidential company's name can also read "(Confidential company)" inside another record, such as a project's `primary_company_id_name`, even for someone on the company's team. Get the company itself to see its name. {% endhint %} ## What `/me` says about the token's user `GET https://api.tiny.plus/me` returns the token's user, with a `permissions` object: | Key | Meaning | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `show_fees` | Whether the account shows this person fee values in pipeline views. The API returns fee fields either way, so hide them in your app if this is `false`. | | `account_admin` | Whether this person is an admin of the account the token is acting for. Only an account admin can [create or change a record on someone else's behalf](#a-token-acts-as-a-person). | | `support_page` | Whether the account shows its Support Docs page in tiny+'s menu. | | `all_records` | For `projects`, `companies` and `contacts`: whether this person may see the company-wide pipeline figures. It doesn't limit which records the API returns. |