# Working with the server API
The features of TrueConf Server can be extended with the RESTful API available in all versions, including the free one.
# How API and OAuth 2.0 work
The API → OAuth2 section is used to manage applications or services which utilize TrueConf Server API. Permissions are controlled based on OAuth 2.0. protocol. You can learn more information about OAuth 2.0. protocol in RFC 6749 official documentation (opens new window) or in the note below.
Oauth 2.0 is used to authorize certain applications (clients) to access protected resources with limited scopes and rights. With this approach, you can block a particular application or a user from the server resources at any given period of time. The protocol also allows you to authorize third-party applications and do actions on the server on behalf of the user via API. In this case, the user does not need to give their username or password to any third-party application (Authorization Code method).
After authorization on TrueConf Server using OAuth 2.0 protocol, every third-party application obtains an access token. Those applications with a valid access token can access TrueConf Server API. The list of API commands can be found in [TrueConf Server API documentation]. TrueConf Server administrator can manage third-party application permissions and access tokens obtained via this section.
Learn more about TrueConf API use cases in our blog.
After successful authorization, the application receives access token with a limited lifespan and scope (server wide or limited to a specific user). For example, server wide scope gives information about any conference on the server, while user’s scope provides the information only about those conferences where the user is the conference owner or a listed participant. The scope is defined by the authorization type selected by a third-party application developer, while permissions set (rights) are determined by TrueConf Server administrator for every application.
| OAuth 2.0 authorization method | Access token scope | Authorization result |
|---|---|---|
| Client Credentials The client gets access token, the scope of which is server wide. User authorization is not performed. This method is recommended for trusted applications only. | Server wide | Access token valid for 1 hour is issued. |
| User Credentials (a.k.a. Resource Owner Password Credentials Grant)
To obtain access token, it is required to provide username and password received on the application side. | User’s scope | Access token valid for 1 hour and (refresh token) valid for 7 days are issued. |
| Authorization Code Access token is issued after user has successfully authorized on TrueConf Server special web page. The application cannot access username and password of the user. | User’s scope | Access token valid for 1 hour and refresh token valid for 7 days are issued. |
| Refresh Token This method is used to obtain a new access token based on your existing refresh token. | Equal to scope of the user who has received refresh token initially | Access token valid for 24 hours is issued. This method cannot be used to obtain new refresh token. |
When requesting an access token, it is required to indicate Application ID and Secret. These parameters can be obtained and updated by creating or editing the application in this section. Application ID is created automatically and cannot be changed later. By contrast, application secret can be further regenerated.
# Permissions
API capabilities of a third-party application depend on the permissions it obtained.
| Permission | Description |
|---|---|
| conferences:read | Reading conference details |
| conferences:write | Creating, editing, and deleting a conference |
| conferences.records:read | Reading conference recording details |
| conferences.participants:read | Reading the list of conference participants |
| conferences.participants:write | Creating, editing, and deleting conference participants |
| conferences.invitations | Reading and editing the list of participants invited to the conference |
| conferences.sessions:read | Reading active video conferencing session details |
| conferences.sessions.participants:read | Reading the list of active conference participants and their roles |
| conferences.sessions.podiums.participants | Inviting a participant of an active conference to the podium and removing the participant from the podium |
| groups:read | Reading user group information |
| groups:write | Creating, editing, and deleting user groups. Unavailable in LDAP mode |
| groups.users:read | Reading the group user list |
| groups.users:write | Creating, editing, and deleting group users. Unavailable in LDAP mode |
| users:read | Reading server user information |
| users:write | Creating, editing, and deleting server users. Unavailable in LDAP mode |
| users.addressbook:read | Reading contacts from user address books |
| users.addressbook:write | Creating, editing, and deleting contacts in the user address book |
| users.avatar:read | Reading user avatars details |
| users.avatar:write | Adding and deleting user avatars |
| templates.conferences:read | Reading conference template details |
| templates.conferences:write | Creating, editing, and deleting conference templates |
| logs.calls:read | Reading the conference list from server logs |
| logs.calls.participants:read | Reading the list of conference participants from server logs |
| logs.calls.invites:read | Reading the list of invited users from server logs |
Each method is assigned with a set of permissions required for successful method call. All sets of permissions are specified in TrueConf Server API documentation.
If an OAuth application requires both read and write access to a certain parameter, then you can specify a general permission <permission> instead of specifying <permission>:read and <permission>:write permissions, if it is available. For example, you don't need to click both users:read and users:write checkboxes to allow an application to read and edit TrueConf Server user accounts. Instead, you can select only the users checkbox.
# Creating new OAuth 2.0 application
To add an OAuth 2.0 application:
Click the Create a new application button.
Enter its identifier in the Name field. It is only displayed in the application list.
To authorize using the Authorization Code method, specify the URL to redirect the application to in the Redirect URL field. For other authorization methods please indicate the following address
https://localhost/.Check the rights required for your application in the Permissions list.
Save your changes by clicking the Create button.
# Editing application
On the application page you can not only edit its properties but also view access token list obtained by the application’s users. You can remove user access tokens at any time to block particular user from accessing API data.
You can also Regenerate the application secret to block the application and its new users from accessing the server for security purposes. Please note that access tokens and refresh tokens obtained using previous application secret will still be valid within their lifespan.