Authentication

You can access the Crosswork Network Controller APIs through an authenticated and authorized account. Only accounts with proper authorization can submit requests to API operations. Ensure that all API communication occurs over a secure HTTPS connection.

Crosswork Network Controller API supports multiple users, each with their own user-specific authorization and set of privileges based on their role. You can associate a user with specific roles to grant access based on their function, and the system can restrict REST endpoints according to the user’s role. The admin user has unrestricted access. For more information on creating and managing users and their roles, see the Cisco Crosswork Network Controller Administration Guide for your release.

The Crosswork Network Controller manages individual users. Crosswork Network Controller includes a single API gateway, which handles all API requests. As such, authenticating using the Crosswork authentication API is sufficient to use all available APIs.

Authentication and Authorization for Crosswork Network Controller APIs

This section explains how to obtain a Ticket Granting Ticket (TGT) and a JSON Web Token (JWT) needed for making secure API calls.

The CNC API supports standard REST HTTP methods and uses JSON-formatted payloads where applicable.

To perform API operations on the CNC platform, you first must authenticate and obtain a JSON Web Token (JWT). The authentication process consists of two steps:

  1. Obtain a Ticket Granting Ticket (TGT): Use your username and password to request a TGT from the Single Sign-On (SSO) server.
  2. Exchange the TGT for a JWT: Use the TGT to request a JWT, and then use the JWT as a Bearer token for subsequent API calls.

Base URL

Every API request starts with the base URL: https://{cnc_host}:{cnc_port}/crosswork/, where {cnc_host} is the CNC management address (host name or IP/virtual IP), and {cnc_port} is the port (for example, 30603) CNC uses for API requests.

For example: https://198.51.100.1:30603

Depending on the specific service, the full URL may contain an additional prefix relative to the base URL and the endpoint that is listed in the API reference.

Step 1: Obtain a Ticket Granting Ticket (TGT)

The first step is to request a Ticket Granting Ticket (TGT) by providing your username and password.

POST URL and Request Payload

  • POST URL https://{cnc_port}:{cnc_port}/crosswork/sso/v1/tickets
  • POST payload: username={user}&password={password} where {user} is the authenticating user name, {password} is the authenticating user's password.

Example

curl -k -s -X POST
https://198.51.100.1:30603/crosswork/sso/v1/tickets
-H 'Content-Type: application/x-www-form-urlencoded'
-H 'Accept: text/plain'
-d 'username=admin&password=abcd123!

Response

TGT-11-O-qlHH4Orn7bwmIQ5fx3Ys6Hrx8Q-cJzQsLqx-ycAD7FQBR5lfb62DFpj-t4shDjRfg-cas-c56784758-s58rs

Save this TGT, because you must use it to request a JWT in the next step.

Step 2: Obtain a JSON Web Token (JWT)

With the TGT obtained in Step 1, you can request a JWT to use for API authentication.

POST URL and Request Payload

  • POST URL: https://{cnc_host}:{cnc_port}/crosswork/sso/v2/tickets/jwt
  • POST Payload: tgt={TGT}&service={service_url} where {TGT} is the TGT received from step 1 above, {service_url} is the CNC landing UI page URL.

Example

curl -k -s -X POST
https://198.51.100.1:30603/crosswork/sso/v2/tickets/jwt
-H 'Content-Type: application/x-www-form-urlencoded'
-d 'tgt=TGT-11-O-qlHH4Orn7bwmIQ5fx3Ys6Hrx8Q-cJzQsLqx-ycAD7FQBR5lfb62DFpj-t4shDjRfg-cas-c56784758-s58rs&service=https://198.51.100.1:30603/app-dashboard'

Response

{
"jwttoken": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCIsImtpZCI6ImU1YmZkZGUwLThlZDMtNDBiZi05ZDZjLTZkY2YzYWU1MjQ0MyJ9.eyJjbGllbnRJ..."
}

Save the jwttoken, as you will use it for subsequent API requests.

Step 3: Using the JWT for Authorization

Once you have the JWT, include it in the Authorization header of your API requests.

Authorization: Bearer {JWT}

Example

curl -k -X GET
https://198.51.100.1:30603/your-api-endpoint
-H "Authorization: Bearer {JWT}"

Replace {JWT} with the token obtained in Step 2.

Note: JWTs are valid for 8 hours. When the token expires, you need to repeat the authentication steps (Step 1 and Step 2) to obtain a new JWT.

Example: Authentication Workflow Using cURL

Step 1: Get TGT

curl -k -s -X POST
https://198.51.100.1:30603/crosswork/sso/v1/tickets
-H 'Content-Type: application/x-www-form-urlencoded'
-d 'username=admin&password=abcdef123!'

Response:

TGT-11-O-qlHH4Orn7bwmIQ5fx3Ys6Hrx8Q-cJzQsLqx-ycAD7FQBR5lfb62DFpj-t4shDjRfg-cas-c56784758-s58rs

Step 2: Get JWT

curl -k -s -X POST
https://198.51.100.1:30603/crosswork/sso/v2/tickets/jwt
-H 'Content-Type: application/x-www-form-urlencoded'
-d 'tgt=TGT-11-O-qlHH4Orn7bwmIQ5fx3Ys6Hrx8Q-cJzQsLqx-ycAD7FQBR5lfb62DFpj-t4shDjRfg-cas-c56784758-s58rs&service=https://198.51.100.1:30603/app-dashboard'

Response:

{
"jwttoken": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCIsImtpZCI6ImU1YmZkZGUwLThlZDMtNDBiZi05ZDZjLTZkY2YzYWU1MjQ0MyJ9.eyJjbGllbnRJ..."
}

Step 3: Use JWT for API Request

curl -k -X GET
https://198.51.100.1:30603/your-api-endpoint
-H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCIsImtpZCI6..."