How to authenticate for Cisco Optical Network Controller API

Authentication

All requests to the Cisco Optical Network Controller API require user authentication.

Cisco Optical Network Controller uses BasicAuth which involves sending a verified username and password with your request.

Append the username with a colon, concatenate it with the password, and encode the result using the Base64 algorithm. For example, given the username Aladdin and password open sesame, the string Aladdin:open sesame is Base64 encoded, resulting in QWxhZGRpbjpvcGVuIHNlc2FtZQ==.

Pass the value through the Authorization HTTP header. The following is an example.

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

A sample cURL request looks like the following:

curl -L --request GET 'https://{CONC-HOST}:8443/api/alarms/currentAlarms' --header 'Accept: application/json' --user {username}:{password}

Rate Limit

Cisco Optical Network Controller Release 3.1 supports up to 5 basic authentication requests per second. Do not make more than 5 requests per second. When this threshold exceeds the limit, the system rejects requests with a 503 (Service Unavailable) status code.

User Roles and Permissions

The following table describes the different user roles and the access levels that Cisco Optical Network Controller provides.

User Role Permission Access Level
Admin permission/admin Allows access to API for all methods.
Supervisor permission/supervisor Allows access to all API for all methods except /v2/devices/fullNetworkSync API of device manager service.
Read-only permission/readonly Allows access only to GET methods for all API.
Internal permission/internal Allows access to all API including internal debug API.
Warning: The internal user role is only for debugging. Do not use the internal permission level without assistance from Cisco Technical Assistance team.

Cisco Optical Network Controller API Authentication Troubleshooting

If you send the wrong credentials, you'll likely receive a 401 Unauthorized status code. This means that the request requires valid credentials and that the server has refused to fulfill the request.

Example Error Message

{
  "error": "Unauthorized",
  "message": "Full authentication is required to access this resource",
  "status": 401
}

Troubleshooting Steps

If you are unable to authenticate, try the following steps:

  1. Verify Credentials: Make sure that the username and password are correct. Credentials are case-sensitive.
  2. Check Base64 Encoding: Ensure proper Base64 encoding of the credentials, as incorrect encoding prevents the server from authenticating your request. Incorrect encoding will prevent the server from authenticating your request.
  3. Copy-Paste Errors: Avoid any extra spaces or invisible characters that can sometimes accompany copy-pasted credentials.
  4. Encoding Tools: Use online tools or command-line utilities to encode your credentials accurately.
  5. API Endpoint: Ensure you are sending the request to the correct API endpoint. An incorrect URL can sometimes lead to a 401 Unauthorized response.
  6. Contact Support: If you've tried all the above and still face issues, contact the Cisco Technical Assistance team for support.