Fortinet Document Library

Version:


Table of Contents

Download PDF
Copy Link

Overview

Introduction

An API (Application Programming Interface) is a set of defined interfaces to accomplish a task, such as retrieving or modifying data. FortiToken Cloud provides a Representational State Transfer (REST) API for interaction with its system components.

This document introduces the supported FortiToken Cloud REST API methods for Web applications, and provides instructions on how to configure and use it.

Audience

Web applications.

API authentication

A client ID and secret combination is required to authenticate for FortiToken Cloud Rest API clients.

New auth client generation

To register for the FortiToken Cloud Rest API client and get the client ID/secret, the FortiToken Cloud customer admin must log in to the FortiToken Cloud portal, go to the Auth Clients>Web Apps page, and then click the Add Auth Client button to create new auth clients for web applications. The client ID and secret will be displayed once on the portal or emailed to the new API client. The client will use the client ID and the secret for future API authentication.

Client ID/secret authentication

The following outlines the process in which a Web application client passes FortiToken Cloud authentication:

  1. The API client calls the Login API with its client ID and secret to request an access token from FortiToken Cloud.
  2. FortiToken Cloud recognizes the client ID and secret and responds with an access token.
  3. The API client puts the access token into the API request authorization header.
  4. FortiToken Cloud checks the API request authorization header to finalize the authentication.
  5. The access token remains valid for an hour, after which the client must call the Login API again to renew the access token.

Accessing FortiToken Cloud Restful API

Any authenticated web application can access the FortiToken Cloud API.

API request general information

FortiToken Cloud API is based on Hypertext Transfer Protocol (HTTP 1.1 and later). The message includes:

  • HTTP method
  • HTTP URL
  • HTTP header and HTTP body

The supported HTTP body format is .JSON. Not all the aforementioned components are required for all HTTP methods, as indicated in the following table:

HTTP Method RFC Request Body Response Body
GET RFC 7231 No Yes
POST RFC 7231 Yes Yes
PUT RFC 7231 Yes Yes
DELETE RFC 7231 No No

Format of URL

All the resource URLs are in the following format:

https://ftc.fortinet.com:[port]/[api/version/resource]

URL Component Description
Port
  • The default service port for external API service is 9696.
  • API REST API.
    Version
  • The supported API version. Currently, it is “v1”.
  • Resource
  • The resource to be accessed.
  • Supported HTTP methods

    Method Description
    GET Retrieves a specific resource with an ID or other fields as the filter.
    POST Creates a new resource on a given endpoint.
    PUT Updates an existing item specified with an ID.
    DELETE Removes an existing item specified with an ID.

    HTTP header

    • Content-type: application/json
    • Authorization header: "Authorization: Bearer [access_token]"
    • Access token: Bearer token, all supported APIs except Login API will need the authorization header

    Example workflow

    Resource API summary

    The following is a summary of the supported APIs. All supported APIs except the Login API must be accessed with the authorization header.

    Resource Resource in URI HTTP methods
    Login /api/v1/login POST
    Realm /api/v1/realm GET
    User /api/v1/user GET, POST, PUT, DELETE
    User Authentication /api/v1/auth GET, POST
    Sync user to FTC /api/v1/user_sync POST
    Task status /api/v1/task GET
    Token /api/v1/token GET

    Count resource

    /api/v1/count

    GET

    Balance

    /api/v1/balance

    GET

    Version

    /version

    GET

    Overview

    Introduction

    An API (Application Programming Interface) is a set of defined interfaces to accomplish a task, such as retrieving or modifying data. FortiToken Cloud provides a Representational State Transfer (REST) API for interaction with its system components.

    This document introduces the supported FortiToken Cloud REST API methods for Web applications, and provides instructions on how to configure and use it.

    Audience

    Web applications.

    API authentication

    A client ID and secret combination is required to authenticate for FortiToken Cloud Rest API clients.

    New auth client generation

    To register for the FortiToken Cloud Rest API client and get the client ID/secret, the FortiToken Cloud customer admin must log in to the FortiToken Cloud portal, go to the Auth Clients>Web Apps page, and then click the Add Auth Client button to create new auth clients for web applications. The client ID and secret will be displayed once on the portal or emailed to the new API client. The client will use the client ID and the secret for future API authentication.

    Client ID/secret authentication

    The following outlines the process in which a Web application client passes FortiToken Cloud authentication:

    1. The API client calls the Login API with its client ID and secret to request an access token from FortiToken Cloud.
    2. FortiToken Cloud recognizes the client ID and secret and responds with an access token.
    3. The API client puts the access token into the API request authorization header.
    4. FortiToken Cloud checks the API request authorization header to finalize the authentication.
    5. The access token remains valid for an hour, after which the client must call the Login API again to renew the access token.

    Accessing FortiToken Cloud Restful API

    Any authenticated web application can access the FortiToken Cloud API.

    API request general information

    FortiToken Cloud API is based on Hypertext Transfer Protocol (HTTP 1.1 and later). The message includes:

    • HTTP method
    • HTTP URL
    • HTTP header and HTTP body

    The supported HTTP body format is .JSON. Not all the aforementioned components are required for all HTTP methods, as indicated in the following table:

    HTTP Method RFC Request Body Response Body
    GET RFC 7231 No Yes
    POST RFC 7231 Yes Yes
    PUT RFC 7231 Yes Yes
    DELETE RFC 7231 No No

    Format of URL

    All the resource URLs are in the following format:

    https://ftc.fortinet.com:[port]/[api/version/resource]

    URL Component Description
    Port
  • The default service port for external API service is 9696.
  • API REST API.
    Version
  • The supported API version. Currently, it is “v1”.
  • Resource
  • The resource to be accessed.
  • Supported HTTP methods

    Method Description
    GET Retrieves a specific resource with an ID or other fields as the filter.
    POST Creates a new resource on a given endpoint.
    PUT Updates an existing item specified with an ID.
    DELETE Removes an existing item specified with an ID.

    HTTP header

    • Content-type: application/json
    • Authorization header: "Authorization: Bearer [access_token]"
    • Access token: Bearer token, all supported APIs except Login API will need the authorization header

    Example workflow

    Resource API summary

    The following is a summary of the supported APIs. All supported APIs except the Login API must be accessed with the authorization header.

    Resource Resource in URI HTTP methods
    Login /api/v1/login POST
    Realm /api/v1/realm GET
    User /api/v1/user GET, POST, PUT, DELETE
    User Authentication /api/v1/auth GET, POST
    Sync user to FTC /api/v1/user_sync POST
    Task status /api/v1/task GET
    Token /api/v1/token GET

    Count resource

    /api/v1/count

    GET

    Balance

    /api/v1/balance

    GET

    Version

    /version

    GET