Securing Your Web-API Requests

On This Page

Overview

You must authenticate your web-API requests to confirm the identity of the sender. You can do this by using any of the supported HTTP user-authentication methods. To further secure your requests, it's recommended that you also use the HTTPS protocol.

HTTPS Requests

The web APIs support sending secure requests using the HTTP Secure (HTTPS) protocol (also known as HTTP over TLS), as defined in the RFC 2818 specification. To send an HTTPS request, simply use an https:// IP address in the request URL.

HTTP User Authentication

Only platform users with relevant permissions can use the web APIs. The web APIs support several alternative methods for authenticating the identity of the user who sent the request:

Note
The examples in the documentation use sample authentication credentials. To run the examples, you must replace the sample credentials with valid credentials for your environment.

Access-Key Authentication

The web APIs support seversal alternative syntax variations for performing access-key authentication:

All of these methods use a platform access key to authenticate the identity of the user. You can get the access key from the platform dashboard: select the user-profile picture or icon from the top right corner of any page, and select Access Keys from the menu. In the Access Keys window, either copy an existing access key or create a new key and copy it. Alternatively, you can get the access key by checking the value of the V3IO_ACCESS_KEY environment variable in a web-shell or Jupyter Notebook service.

Remote Access

If you have the Developer management policy, you can copy the relevant parameters that enable you to work remotely. Press the user icon (User), then press Remote settings (User). The settings are copied to your clipboard.

X-v3io-session-key Authentication

The web APIs support a custom X-v3io-session-key HTTP request header for access-key requests authentication. The value of the header is a platform access key.

X-v3io-session-key: <access key>

Copy

 Copied to clipboard

For example, a request with the following header will be authenticated with the "e8bd4ca2-537b-4175-bf01-8c74963e90bf" access key:

X-v3io-session-key: e8bd4ca2-537b-4175-bf01-8c74963e90bf

Copy

 Copied to clipboard

S3-Like Authentications

To simplify porting Amazon Simple Storage Service (S3) code to the platform, the web APIs support the following AWS signature authentication variations; just replace your S3 access key in the Authorization header with a platform access key. For both variations, the platform extracts the access key from the header value (<access key>) and uses it to authenticate the request; any other information in the header, such as an S3 signature, is ignored.

  • AWS signature version 4 (AWS4) authentication syntax —

    Authorization: AWS4-<...>Credential=<access key>/[...]

    Copy

     Copied to clipboard

    For example, a request with the following header will be authenticated with the "e8bd4ca2-537b-4175-bf01-8c74963e90bf" access key:

    Authorization: AWS4-HMAC-SHA256 Credential=e8bd4ca2-537b-4175-bf01-8c74963e90bf/20190422/us-east-1/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=4708b8682367fff1ba5d33662a6a7bdbefa743b52e4744aedbd919ca73ce70f5

    Copy

     Copied to clipboard

  • AWS signature version 2 (AWS2) authentication syntax —

    AWS <access-key>:<signature>

    Copy

     Copied to clipboard

    For example, a request with the following header will be authenticated with the "e8bd4ca2-537b-4175-bf01-8c74963e90bf" access key:

    Authorization: AWS e8bd4ca2-537b-4175-bf01-8c74963e90bf:frJIUN8DYpKDtOLCwo//yllqDzg=

    Copy

     Copied to clipboard

Basic HTTP Username/Password Authentication

To use the username/password "Basic" HTTP authentication scheme, as defined in the RFC 7617 and RFC 7235 specifications, do the following: add an Authorization request header with the Basic authentication-scheme token followed by a Base64 string that encodes the username and password login credentials:

Authorization: Basic <Base64-encoded credentials>

Copy

 Copied to clipboard

For example:

Authorization: Basic iguazio:$apr1$YgrCYAYo$6v6iumigwirH4Jsdt4MWr0

Copy

 Copied to clipboard

Postman Note
When using Postman, select the Authorization tab, select the "Basic Auth" authorization type, and enter your username and password in the respective fields. Postman will encode the login credentials and create the required header.

See Also