Service applications

  1. Connect service applications
  2. Examples of requests for managing user resources

Service applications are used to manage user resources in an organization via the API. For example, you can use them to back up your emails or manage events in Yandex Calendar. You can create up to 20 service applications.

Service applications are available for Optimal and Advanced service plans. If you disable the plan, you won't be able to manage service applications. You can clear the list of applications within a month. After one month, the applications will be removed from the organization.

Attention. Under clause 3.7 of the offer, after enabling access, the admin is obliged to notify all users and, if necessary, obtain their written consent (unless it was obtained earlier).

Connect service applications

  1. Log in to the account of the company owner.

  2. Register an application that will manage the list of service applications in the organization.

    1. Open the Create an OAuth app page.
    2. Enter the name of your service and attach an icon if necessary.
    3. In the Platforms block, select Web services. In the Redirect URI field, click Enter URL for debugging.

    4. In the Data access section, specify the access rights that are required to manage service applications in the organization:

      • ya360_security:service_applications_read: To read the list of service applications.
      • ya360_security:service_applications_write: To manage the list of service applications (read and write).
    5. Add your contact email. At the bottom of the page, click Create application. Its description will appear on the screen.
    6. Copy the application ID from the ClientID field. You'll need it to get an OAuth token. In the future, the page with all your applications will be available at oauth.yandex.ru.

  3. Request an OAuth token in any way convenient to you. You'll need it later to register all service applications in the organization.

    You can get a debug OAuth token manually:

    1. Follow the link

      https://oauth.yandex.ru/authorize?response_type=token&client_id=<main_app_client_id>
      Copied to clipboard

      Replace <main_app_client_id> with the value of ClientID from Step 2.6.

    2. If the OAuth token is issued to your application for the first time, an authorization screen will open. After logging in, Yandex OAuth will redirect you to the page with the token. Learn more about debug tokens.

  4. Notify users and obtain their consent (unless it was obtained earlier) to the admin's access to their resources in accordance with clause 3.7 of the offer.

  5. Activate the service applications function using the following request:

    POST https://api360.yandex.net/security/v1/org/<org_id>/service_applications/activate
    Copied to clipboard

    Replace <org_id> with your company identifier.

  6. Register the service application. You can use it to get temporary OAuth tokens. A temporary token is valid for 1 hour.

    1. Create a separate OAuth application in the same way you created the main application (Step 2). Specify the access rights for this application that will be used in API requests.

    2. Make the application from the previous step the service application for the organization.

      Example
      curl --location \
--request POST 'https://api360.yandex.net/security/v1/org/<org_id>/service_applications' \
--header 'Authorization: OAuth <owner_token_to_manage_service_app>’ \
--header 'Content-Type: application/json' \
--data-raw '{ \
  "applications": [ \
    { \
      "id": “<OAuth_service_app_client_id>”, \
      "scopes": [ \
        "cloud_api:disk.app_folder", \
        "cloud_api:disk.read", \
        "cloud_api:disk.write", \
        "cloud_api:disk.info" \
      ] \
    } \
  ] \
}'
      Copied to clipboard

      Substitute the following values into the code:

      • <org_id>: Your company identifier.
      • <owner_token_to_manage_service_app>: The OAuth token from Step 3.
      • <OAuth_service_app_client_id>: ClientID of the service application from Step 6.1.

    3. Check that the application was added as a service application.

      Example
      curl --location  \
--request GET 'https://api360.yandex.net/security/v1/org/<org_id>/service_applications'  \
--header 'Authorization: OAuth <owner_token_to_manage_service_app>'
      Copied to clipboard

    To connect other service applications, repeat Step 6.

  7. Get a temporary user token. You can do this using the following API request:

    POST /token HTTP/1.1
   Host: http://oauth.yandex.ru
   Content-type: application/x-www-form-urlencoded
    Copied to clipboard
    Example
    curl --location \
--request POST 'https://oauth.yandex.ru/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
--data-urlencode 'client_id=<OAuth_service_app_client_id>' \
--data-urlencode 'client_secret=<OAuth_service_app_client_secret>' \
--data-urlencode 'subject_token=<user_id>' \
--data-urlencode 'subject_token_type=urn:yandex:params:oauth:token-type:uid'
    Copied to clipboard

    or

    curl --location 
--request POST 'https://oauth.yandex.ru/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
--data-urlencode 'client_id=<OAuth_service_app_client_id>' \
--data-urlencode 'client_secret=<OAuth_service_app_client_secret>' \
--data-urlencode 'subject_token=<user_email>' \
--data-urlencode 'subject_token_type=urn:yandex:params:oauth:token-type:email'
    Copied to clipboard

    Substitute the following values into the code:

    • <OAuth_service_app_client_id>: ClientID of the service application from Step 6.1.
    • <OAuth_service_app_client_secret>: Client secret of the service application.
    • <user_id>: Identifier of the user who receives a token.
    • <user_email> : Email address of the user who receives a token in the format [email protected].

    The response will contain a token that the user must use in their requests to Yandex 360 API services.

Service application management is described in detail in API 360 Help.

Examples of requests for managing user resources

Temporary tokens issued by service applications provide API access to some user resources in the organization, for example, to back up data or search for information.

Yandex Disk

The Yandex.Disk API is intended for working with files and managing access to them. You can send requests to the Yandex Disk API using Polygon.

Example

Request for meta-information about the employee's Yandex Disk:

curl --request GET 'https://cloud-api.yandex.net/v1/disk' \
--header 'Accept: application/json' \
--header 'Authorization: OAuth <oauth_token>'
Copied to clipboard

Replace <oauth_token> with the value of the temporary token from Step 7.

Learn more about working with the Yandex Disk REST API.

Yandex Mail

Applications can access Yandex Mail mailboxes via the OAuth protocol. OAuth authorization is supported by IMAP and SMTP Yandex Mail servers.

Example

Python script for counting user emails using the IMAP protocol:

import imaplib

def generate_oauth2_string(username, access_token):
    auth_string = 'user=%s\1auth=Bearer %s\1\1' % (username, access_token)
    return auth_string

def get_imap_connector(username="<user_email>", token="<oauth_token>"):
    auth_string = generate_oauth2_string(username, token)
    imap_connector = imaplib.IMAP4_SSL("imap.yandex.com", 993)
    imap_connector.authenticate('XOAUTH2', lambda x: auth_string)
    return imap_connector

def get_total_emails(imap_connector):
    mailboxes = []
    ttl_emails = 0
    for mailbox in imap_connector.list()[1]:
        mailboxes.append(mailbox.decode("utf-8").split()[-1].replace('"', ''))
        for mailbox in mailboxes:
            try:
                imap_connector.select(mailbox)
                resp_code, mail_count = imap_connector.select(mailbox=mailbox, readonly=True)
                ttl_emails += int(mail_count[0].decode("utf-8"))
            except imaplib.IMAP4.error:
                print(f"Folder: {folder} Error reading emails")
            except ValueError:
                print(f"Folder: {folder} Error reading emails")
    user_logout(imap_connector)
    return ttl_emails

get_total_emails(get_imap_connector())
Copied to clipboard

Substitute the following values into the code:

  • <user_email>: Email address of the user whose data is retrieved in the format [email protected].
  • <oauth_token>: Temporary user token from Step 7.

For more information about how mail protocols work, see the IMAP description and SMTP specifications.

Yandex Calendar

OAuth tokens can be used to interact with Yandex Calendar via the CalDAV protocol.

Example 1

Python script to delete the user's Yandex Calendar:

import caldav

def get_principal(username, leg_token):
    client = caldav.DAVClient(url=url, username=username, password=leg_token)
    principal = client.principal()
    return principal

my_principal = get_principal("<user_email>", "<oauth_token>")

def find_delete_calendar(my_principal, calendar_name="My calendar"):
    try:
        calendar = my_principal.calendar(name=calendar_name)
        assert calendar
        print(f"We found an existing calendar with name {calendar_name}, now deleting it")
        calendar.delete()
    except caldav.error.NotFoundError:
        print("Calendar was not found")

find_delete_calendar(my_principal)
Copied to clipboard

Substitute the following values into the code:

  • <user_email>: Email address of the user whose data is retrieved in the format [email protected].
  • <oauth_token>: Temporary user token from Step 7.
Note. If the admin deletes the user's calendar, neither the admin nor the user will be able to restore it in the future.
Example 2

Requests to create a meeting in Yandex Calendar with a link to a video meeting in Yandex Telemost:

  • A conference for a one-time event.

    curl -v "https://caldav.yandex.ru/calendars/<user_email>/events-default/<event_uid>.ics" \
  -H "Authorization: OAuth <oauth_token>" \
  -H "Content-type: text/ics" \
  -X PUT \
  --data-binary "
    BEGIN:VCALENDAR
    BEGIN:VEVENT
    X-TELEMOST-REQUIRED:TRUE
    DESCRIPTION:Single event
    UID:<event_uid>
    DTSTART:20230417T120000Z
    END:VEVENT
    END:VCALENDAR"
    Copied to clipboard

    Substitute the following values into the code:

    • <user_email>: Email address of the user whose data is retrieved in the format [email protected].
    • <event_uid>: Meeting and file name identifier (for example, a5e3e7b0-dd11-11ed).
    • <oauth_token>: Temporary user token from Step 7.

    Example of a successful response:

    HTTP/1.1 201 Created

  • A conference for a recurring event.

    curl -v "https://caldav.yandex.ru/calendars/<user_email>/events-default/<event_uid>.ics" \
  -H "Authorization: OAuth <oauth_token>" \
  -H "Content-type: text/ics" \
  -X PUT \
  --data-binary "
    BEGIN:VCALENDAR
    BEGIN:VEVENT
    X-TELEMOST-REQUIRED:TRUE
    DESCRIPTION:Weekly event
    UID:<event_uid>
    DTSTART:20230411T200000Z
    RRULE:FREQ=WEEKLY
    END:VEVENT
    END:VCALENDAR"
    Copied to clipboard

    Substitute the following values into the code:

    • <user_email>: Email address of the user whose data is retrieved in the format [email protected].
    • <event_uid>: Meeting and file name identifier (for example, a5e3e7b0-dd11-11ed).
    • <oauth_token>: Temporary user token from Step 7.

    Example of a successful response:

    HTTP/1.1 201 Created

When sending the PUT request to create or change an event in the calendar, the client adds the non-standard property X-TELEMOST-REQUIRED to VEVENT components. When the server receives the request, it generates a link to the video conference in Yandex Telemost and adds it to the meeting description.

When the client reads the conference, the server doesn't specify the X-TELEMOST-REQUIRED property. But if the link to the video meeting in Yandex Telemost was generated, it returns this link in the X-TELEMOST-CONFERENCE non-standard property.

For more information about working with the CalDAV protocol, see the specifications.