Requesting Authorization

In this article

    The Veeam Backup for GCP REST API accepts the following grant types to authenticate a Veeam Backup for GCP user:

    Using Password Grant Type

    To obtain authorization tokens, a user sends the HTTP POST request to the api/v1/token/ endpoint.

    The request body must contain the grant_type parameter with the specified password value and the credentials of a user created in Veeam Backup for GCP. For more information on how to create users, see User Accounts or the Veeam Backup for GCP User Guide, section Adding Backup Administrator Accounts.

    Tip

    If you want to change the expiration period of the refresh token to 60 minutes, set the use_short_term_refresh parameter value to true.

    A successfully completed operation returns the 200 response code. In the response body, Veeam Backup for GCP returns an access token, its expiration time (in seconds) and a refresh token. The user inserts the access token in headers of further requests to the Veeam Backup for GCP REST API. The refresh token must be saved locally.

    To learn how to authorize your access using the password grant type, see Example [Password]. Alternatively, you can use the Swagger UI.

    Using MFA Grant Type

    Note

    MFA is disabled by default. To learn how to enable MFA, see Multi-Factor Authentication or the Veeam Backup for GCP User Guide, section Enabling Multi-Factor Authentication.

    If multi-factor authentication (MFA) is enabled for a user, the user must first obtain an mfa token, and then get authorization tokens.

    1. To obtain an mfa token, the user sends the HTTP POST request to the api/v1/token/ endpoint. The request body must contain the grant_type parameter with the specified password value and the credentials of the user.

    A successfully completed operation returns the 202 response code. In the response body, Veeam Backup for GCP returns an mfa token.

    1. To obtain an access token and a refresh token, the user must send another HTTP POST request to the api/v1/token/ endpoint. The request body must contain the grant_type parameter with the specified mfa value, the mfa token previously received from the authorization server, and the verification code generated by the authentication application running on the trusted device.

    A successfully completed operation returns the 200 response code. In the response body, Veeam Backup for GCP returns an access token, its expiration time (in seconds) and a refresh token. The user inserts the access token in headers of further requests to the Veeam Backup for GCP REST API. The refresh token must be saved locally.

    To learn how to authorize your access using the MFA grant type, see Example [MFA]. Alternatively, you can use the Swagger UI.

    Using Authorization Code Grant Type

    To get authorization using the Authorization Code grant type, a user must first obtain an authorization code, and then get authorization tokens.

    1. To obtain the authorization code, an authorized user sends the HTTP POST request to the /api/v1/authorization_code endpoint.

    A successfully completed operation returns the 200 response code. In the response body, Veeam Backup for GCP returns an authorization code, which can be used by another user or client application to get authorization in the Veeam Backup for GCP REST API. By default, the Veeam Backup for GCP authorization code expires in 60 seconds.

    1. To obtain an access token and a refresh token, a user or client application sends the HTTP POST request to the /api/v1/token endpoint. The request body must contain the grant_type parameter with the specified authorization_code value and the authorization code previously issued by the authorization server.

    A successfully completed operation returns the 200 response code. In the response body, Veeam Backup for GCP returns an access token, its expiration time (in seconds) and a refresh token. The user inserts the access token in headers of further requests to the Veeam Backup for GCP REST API. The refresh token must be saved locally.

    To learn how to authorize your access using the Authorization Code grant type, see Example [Authorization Code]. Alternatively, you can use the Swagger UI.

    Requesting AuthorizationExample [Password]

    To obtain an access token and a refresh token, a user sends the HTTP POST request to the /api/v1/token endpoint. In the x-api-version header, the user specifies the current revision of the Veeam Backup for GCP REST API.

    In the request body, the user specifies the following parameters:

    • grant_type — the password value must be specified for this parameter.
    • username and password — credentials used to access the server; in this example, administrator and Password1 are used.

    Request:

    POST https://127.0.0.1:13140/api/v1/token

     

    Request Header:

    x-api-version:1.0-rev0

     

    Request Body:

    grant_type=password&username=administrator&password=Password1

    The server sends a response in the following format.

    Response:

    200

    Response Body:

    {

     "access_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IkQzMjUyMThDOUMwMTYxODU1MzkxMjk1RTlDODQ4MTFGODZEODIwRTYiLCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InJvb3QiLCJuYmYiOjE2MTY0NDU2OTEsImV4cCI6MTYxNjQ0NjU5MSwiaWF0IjoxNjE2NDQ1NjkxLCJhdWQiOiJhY2Nlc3MifQ.WbV8s8obbsMo13DoL3ihw_Tr0DhjVcYXarMWWWDcDyalRBmMNTer086mNBWnlmYdTmWrPPcXF9pWna4fik9o_WFsvOfvEtEhuJ9RfKUfwv4BBfQzRJfyQuGxBonMcxVCuf5NNz0zDx9nC6-950kEIfBGtuR0r891h3n_45Dm-AeTlPtYliTW8hbWuvWEZ-0LXrgIUEuAqvtZTSxuIIC_ItwWumzhZ1VNujC7CbtGEcg6QjQbkVcg0tQDe2dhZUmjzk3h48YWB9MkF3CrBFzMlTWGkpc56vKsrxKLTkWdpeUgg-79wsX9H1jz-rThGVVkZtAmHSJkNA4fd8opRKCRUg",

     "token_type": "bearer",

     "refresh_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IkQzMjUyMThDOUMwMTYxODU1MzkxMjk1RTlDODQ4MTFGODZEODIwRTYiLCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InJvb3QiLCJ0b2tlbl9pZCI6IjYxMzBjMmM0LTE1MzEtNGI4NC1hZTBjLThjMjg0YTJkOTA1NCIsInNob3J0X3Rlcm1fZXhwaXJhdGlvbiI6IkZhbHNlIiwibmJmIjoxNjE2NDQ1NjkxLCJleHAiOjE2MTc2NTUyOTEsImlhdCI6MTYxNjQ0NTY5MSwiYXVkIjoicmVmcmVzaCJ9.X0oJZ0E6gckK4Rk56cE1q1NVlPwAIrsOBDwIpERmio3M-6OkRP9FrHj-j6LSLkKcEa3qCwbm89zPvoMDz8chYl8ExEj4C9zNmH9NapJg2I-owmOx6VgP4cHVRE2VkcCkm4FAU0kPj0EQtEsmezIyInCJ6r3kVh9qKiB_sz_k6gc7etNHP1rS4uxxTwey4mdrtl7QVy1AKjU36ZX_V3N19lvTNPXhUwtB6v4Nau9f2bvTbRD6jE26OTWDdvaE87RBGSofk4NhlRO98wuReM2hFCOlqFi7AsCKnsHk_1C0g1OItYAYoxv3TH8Ti5xT2oNO78m3Oqc1BEIqP7U37jjzZw",

     "expires_in": 900,

     ".issued": "2021-03-22T20:41:31",

     ".expires": "2021-03-22T20:56:31"

    }

    Requesting AuthorizationExample [MFA]

    To access the REST API when MFA is enabled, a user must do the following:

    1. To obtain an mfa token, the user sends the HTTP POST request to the api/v1/token/ endpoint. In the x-api-version header, the user specifies the current revision of the Veeam Backup for GCP REST API.

    In the request body, the user specifies the following parameters:

    • grant_type — the password value must be specified for this parameter.
    • username and password — credentials used to access the server; in this example, administrator and Password1 are used.

    Request:

    POST https://127.0.0.1:13140/api/v1/token

     

    Request Header:

    x-api-version:1.0-rev0

     

    Request Body:

    grant_type=password&username=administrator&password=Password1

    The server sends a response in the following format.

    Response:

    202

    Response Body:

    {

     "mfa_token": "NzMxODI0QjQ4MjY5NTVCMUExNkU0NDc5QUFBRThEN0EwRjEyQ0M3RTk3QzkwNjU4NTgxQzg4MUNCMDQxRTYxQg==",

     "description": "mfa required"

    }

    1. To obtain an access token and a refresh token, the user sends the HTTP POST request to the api/v1/token/ endpoint. In the x-api-version header, the user specifies the current revision of the Veeam Backup for GCP REST API.

    In the request body, the user specifies the following parameters:

    • grant_type — the mfa value must be specified for this parameter.
    • mfa_token — the mfa token previously received from the authorization server.
    • mfa_code — the six-digit verification code generated by the authentication application running on the trusted device.

    Request:

    POST https://127.0.0.1:13140/api/v1/token/

     

    Request Header:

    x-api-version:1.0-rev0

     

    Request Body:

    grant_type=mfa&mfa_token=RUI3Q0VCMUU3RTAzMTk5RUVCRjk3RjVGMDhCNzQ2MkU0QTgzMzRGQkFBMzJGM0YyNzQwQ0QxMzU1REMwOUEzMw%3D%3D&mfa_code=962724

    The server sends a response in the following format.

    Response:

    200

    Response Body:

    {

     "access_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IkVDQTM3OTczM0U5MzhDMjRBMjQzMkE4MTJBNzAwNEYzMzdBRTAyQjgiLCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InR3X3Rlc3QiLCJuYmYiOjE2MTY3NzQ0MDYsImV4cCI6MTYxNjc3NTMwNiwiaWF0IjoxNjE2Nzc0NDA2LCJhdWQiOiJhY2Nlc3MifQ.yfKXBFwyew7K5z0ioTSyM-MdbrOBo9PfbsTXrMUPXp4zC_we2yVrfjjDorYslMQmxEib42fjd36XCh1MBAapDreD4mWO8a4y9BNpLbp_7i4yn5NyZhxngy1wJ0mV3Z6R0M82PcCPSqnhl2Cf6zFdOaVqeW26TfGzKfCfArYf8rPpwDA0rJkslSC_YZJbSk4OthkgY8R8zAbWunW1ss1d7BW81FT0oAbkEFahlPfpJURPj7uq73GyOQ8SvKc68HYvTI6G9jKQrzVh-pI3hxqTh5F8eU18_eC5yqGpzxa1zJlBjc9WKRMdTwPyGxHhnSmrQTKlfbT_OTTYuT7gE4Y0jw",

     "token_type": "bearer",

     "refresh_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IkVDQTM3OTczM0U5MzhDMjRBMjQzMkE4MTJBNzAwNEYzMzdBRTAyQjgiLCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InR3X3Rlc3QiLCJ0b2tlbl9pZCI6IjczYjZiMWEyLTQxZjMtNGU1Mi1hZWVhLTNiZTUyYzVmZGMyNSIsInNob3J0X3Rlcm1fZXhwaXJhdGlvbiI6IkZhbHNlIiwibmJmIjoxNjE2Nzc0NDA2LCJleHAiOjE2MTc5ODQwMDYsImlhdCI6MTYxNjc3NDQwNiwiYXVkIjoicmVmcmVzaCJ9.zAYGBx9BDFjaN-E2ZmZOjz0EYpFZJraz7F2cHX5PDcTpDR5CEDGla0X29k4-2qUC-pL3bwr77TxwaKskHsS2JXM8t8aQJxs2CFUPrKlYdxPBHzNqdLC9-CrAOaX1mzF3o2GbzYzKh1v62HDNJLuaH67Jy7kUr7LbGxQ1tB9oJZYVAIes6RjVLO58sKariWdpjvt-38Wl8OYHbuS2YL6_54cnTWslitfPLsz6w4eUk_aZUlwOnhJ4NVfHWt4mbVu9V6mR4mowwsXul_A0SAF_uP0eTs_DpRy8FAdPi5lTiwbVxpJ9d0GQoBr-fjlGIdYqT540Kk8DsGgHH6HyMkw4Cw",

     "expires_in": 900,

     ".issued": "2021-03-26T16:00:06",

     ".expires": "2021-03-26T16:15:06"

    }

    Requesting AuthorizationExample [Authorization Code]

    To access the REST API using an authorization code, a user must do the following:

    1. To obtain an authorization code, an authorized user sends the HTTP POST request to the /api/v1/authorization_code endpoint. In the x-api-version header, the user specifies the current revision of the Veeam Backup for GCP REST API, in the Authorization header — currently valid access token in the Bearer <access_token> format.

    Request:

    POST https://127.0.0.1:13140/api/v1/authorization_code

     

    Request Header:

    x-api-version:1.0-rev0

    Authorization:Bearer eyJhbGciOiJSUzUxMiIsImtpZCI6IjQ2MDU0QjExNTE3Njk0QzAxN0IyRTE2MTQyNURCRDM1QkNGNzY3NkQi-LCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InVzZXIiLCJuYmYiOjE1ODYyNTUzNzksImV4cCI6MTU4NjI1NjI3OSwiaWF0IjoxNTg2MjU1Mzc5LCJhdWQiOiJhY2Nlc3MifQ.kOCwrbf6BErst5X-ZOK5zSVH9htMN5GJpPkE1MScDM08iHrF4vPZaGGlHGZzvLu6eJmzyM-GA9zG5QAoPQcQCxzhUf4btj6JvUd1thz3BgfSfCvDh_nQUG-WQ5dAkeOL8M7sze6nlHRDJDg1b7D2Ev7BsFg41ip24drWl2wyebZVZXBOwpIsD7rbX1fJW3FHfvEMyes7h8gWruHtqc-6uJnMuA7YJc706rlXHf6wgpLJAaW2qRAwtBUpE6kib9odU58Hc2aS5QqQBwwKX6hTI3ZbBDg_B5KW6xL7rRIMbtTgdEhbDn41WMPhINS9yAFf7sKvdsofStPX31H0Mt1eOg

    The server sends a response in the following format.

    Response:

    200

    Response Body:

    {

     "code": "AAEAAJO1R+DANfH7JDlyUzDVYGDw+77dyaa0mFu8nozvbOreW31Uu1X+mejLUilSp6nBrhcmv9/LTjAjMz3P+grbg1OATjZN7kZ5XbhenJG7DrVUtvpA6h5aDmma8INsMv6xW7+TmcOUNlK65n2J2/rQCjg80rMOSjlpnkQkX2s+tXOxkX+h/GTRSdxCulLhn69Rj+8Qvmh3+h8c3g+RVnhfSWwfxVR1+sFtViNQwQzI3hBRvxivb9IZo9WSYgtDJc8816OrUrIn26h71jYm6WfYn3ZiMp/VkABHqvqAsIMuKD1Xat9lnQyxARc1ZU9suM7Ivd5I7Ew51vMMPhXMetchrGkIAAAAWccK8uTa1wg="

    }

    1. To obtain an access token and a refresh token, the user sends the HTTP POST request to the /api/v1/token endpoint. In the x-api-version header, the current revision of the Veeam Backup for GCP REST API must be specified.

    In the request body, the user specifies the following parameters:

    • grant_type — the authorization_code value must be specified for this parameter.
    • code — the authorization code previously issued by the authorization server.

    Request:

    POST https://127.0.0.1:13140/api/v1/token

     

    Request Header:

    x-api-version:1.0-rev0

     

    Request Body:

    grant_type=authorization_code&code=AAEAAJO1R+DANfH7JDlyUzDVYGDw+77dyaa0mFu8nozvbOreW31Uu1X+mejLUilSp6nBrhcmv9/LTjAjMz3P+grbg1OATjZN7kZ5XbhenJG7DrVUtvpA6h5aDmma8INsMv6xW7+TmcOUNlK65n2J2/rQCjg80rMOSjlpnkQkX2s+tXOxkX+h/GTRSdxCulLhn69Rj+8Qvmh3+h8c3g+RVnhfSWwfxVR1+sFtViNQwQzI3hBRvxivb9IZo9WSYgtDJc8816OrUrIn26h71jYm6WfYn3ZiMp/VkABHqvqAsIMuKD1Xat9lnQyxARc1ZU9suM7Ivd5I7Ew51vMMPhXMetchrGkIAAAAWccK8uTa1wg=

    The server sends a response in the following format.

    Response:

    200

    Response Body:

    {

     "access_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IkVDQTM3OTczM0U5MzhDMjRBMjQzMkE4MTJBNzAwNEYzMzdBRTAyQjgiLCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InJvb3QiLCJuYmYiOjE2MTY3NzUyMzQsImV4cCI6MTYxNjc3NjEzNCwiaWF0IjoxNjE2Nzc1MjM0LCJhdWQiOiJhY2Nlc3MifQ.CdlhUaXbGsl-H-BJz_gRHSO-4OrcWTN8Wlayl9bFvkj9cYxF5X09Io1CYky4jiYrEAK3mjHdK_Os9UJ3wOCH-4e0OPaY67-ZH5rXDIAq3CxmKkQ4MN7N-le0expKoQKCMsvEa8GOKvX1KulqrxRGdW3g9aptnUY5_1gyE4YHYbc4eAZBY2MjA9qXn-rufT1ExrRNgAtcIRPTRoMm_N-ryd6uWEFLi2TrGjgc9RCJECMPq9Rx6s3O5G-rCVIjUgdAMyElUSx-8JhDQx2VByIDzrYWwT8J4jS8YDWhV95iVSbQ5IsP3VLjqxGytpCKmCTqMUJUOelcVKKxaNbwvs7DTQ",

     "token_type": "bearer",

     "refresh_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IkVDQTM3OTczM0U5MzhDMjRBMjQzMkE4MTJBNzAwNEYzMzdBRTAyQjgiLCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InJvb3QiLCJ0b2tlbl9pZCI6IjE5Nzg2MDg4LTQzOTAtNGVkMi04ZTRhLTU0MjUxMDdiNGRlNCIsInNob3J0X3Rlcm1fZXhwaXJhdGlvbiI6IlRydWUiLCJuYmYiOjE2MTY3NzUyMzQsImV4cCI6MTYxNjc3OTczNCwiaWF0IjoxNjE2Nzc1MjM0LCJhdWQiOiJyZWZyZXNoIn0.xZ06XwQa7sYAiGxOJ9wtLbBB7zICuyT6gnEAY9dVtOEspqdGAUJ2IUTfrOPW3n7NdaYhnFQF5yvbsuBiVB_MLjIdnwo_Lx8ekBLZLeFKNZ446XeCzFLhRZYygcsh-S2cabztJrK6qjBeisY3LFk1UqccwhzKZg4dd-U-OxszMAR47KZCh1je4fpECNoMVkXkM9IjYJca-y73zIbrCZbb9JE2rdUiUdtO5olmbJYy5UpzetKSnLlZ2z2y7DRfudOqNg9SA9igQtxCvkVg_Bd2Wvqg5ctvLo31uXIU4nqnzI_54DFWJEHv-XEGone7ABqk0_lDmzgCTy4joaq1EzVRvw",

     "expires_in": 900,

     ".issued": "2021-03-26T16:13:54",

     ".expires": "2021-03-26T16:28:54"

    }