Getting started with the Connector Appliance APIs
To use the Connector Appliance APIs, you must have the following information:
-
The IP address of your Connector Appliance.
You can find this IP address on the Connector Appliance console.
-
An authorization token.
Use the API to request an authorization token. This token is valid for 15 minutes. After this time you must request a new token to continue using the API.
Retrieve an authorization token
Follow these steps to get an authorization token to use with the Connector Appliance API:
- Check whether you have credentials set up on your Connector Appliance.
- If the credentials are not yet set up, set up the credentials.
- Log in with the credentials to retrieve the authorization token.
If you already set up your password when you first logged in to the Connector Appliance administration page or by using the API, go straight to step 3, Log in.
Check whether credentials are set up
This call lets you know whether a user name and password have already been set up for this Connector Appliance.
Request
GET /credentials HTTP/1.1
Accept: */*
Host: <connector-appliance-ip-address>
Connection: keep-alive
<!--NeedCopy-->
Responses
Credentials are set up
HTTP/1.1 200 OK
Cache-Control: no-cache, no-store
Citrix-Transactionid: <id>
Content-Length: 29
Content-Security-Policy: frame-ancestors 'none'
Content-Type: application/json; charset=utf-8
Date: <date>
X-Content-Type-Options: nosniff
X-Frame-Options: deny
{"credentialsAreSetup":true}
<!--NeedCopy-->
If you receive this response, your credentials are already set up. Use your existing credentials to log in.
If you don’t know what credentials are set up on this Connector Appliance, you cannot use the API or administration page to access it and must reinstall the Connector Appliance. For more information, see the product documentation.
Credentials are not set up
HTTP/1.1 200 OK
Cache-Control: no-cache, no-store
Citrix-Transactionid: <id>
Content-Length: 30
Content-Security-Policy: frame-ancestors 'none'
Content-Type: application/json; charset=utf-8
Date: <date>
X-Content-Type-Options: nosniff
X-Frame-Options: deny
{"credentialsAreSetup":false}
<!--NeedCopy-->
If you receive this response, you must set up credentials before you can log in and retrieve an authorization token.
Set up credentials
Set a password to use to authenticate with your Connector Appliance.
Notes:
- The value of user name must be
admin.The password you set must meet the following requirements:
- 8 or more characters long
- Contains both upper and lower case letters
- Contains at least one non-alphabetic character
- Credentials can only be set up once. If you have already set up your credentials, this call does not succeed.
- You can also set these credentials when going to the Connector Appliance administration page for the first time. For more information, see the product documentation.
Request
POST /credentials HTTP/1.1
Content-Type: application/json
Accept: */*
Host: <connector-appliance-ip-address>
Content-Length: <length>
{"username": "admin", "password": "<password>"}
<!--NeedCopy-->
Responses
Success
HTTP/1.1 201 Created
Cache-Control: no-cache, no-store
Citrix-Transactionid: <id>
Content-Length: <length>
Content-Security-Policy: frame-ancestors 'none'
Content-Type: application/json; charset=utf-8
Date: <date>
X-Content-Type-Options: nosniff
X-Frame-Options: deny
{"status":"success","details":"Credentials set"}
<!--NeedCopy-->
Credentials already set up
HTTP/1.1 500 Internal Server Error
Cache-Control: no-cache, no-store
Citrix-Transactionid: <id>
Content-Security-Policy: frame-ancestors 'none'
Content-Type: application/json; charset=utf-8
Date: <date>
X-Content-Type-Options: nosniff
X-frame-Options: deny
Content-Length: <length>
{"type":"https://errors-api.cloud.com/connapp/servererror","detail":"Server error"}
<!--NeedCopy-->
Log in
To retrieve the authorization token, log in with the credentials that you set through the API or in the Connector Appliance administration page. The user name is always admin.
Request
POST /$login HTTP/1.1
Content-Type: application/json
Accept: */*
Host: <connector-appliance-ip-address>
Content-Length: <length>
{"username": "admin", "password": "<password>"}
<!--NeedCopy-->
Responses
Success
The success message includes the authorization token. Store this value and use it in your subsequent calls to the API of this Connector Appliance.
HTTP/1.1 200 OK
Cache-Control: no-cache, no-store
Citrix-Transactionid: <id>
Content-Length: <length>
Content-Security-Policy: frame-ancestors 'none'
Content-Type: application/json; charset=utf-8
Date: <date>
X-Content-Type-Options: nosniff
X-Frame-Options: deny
{"token":"abcde.12345.ABCDE"}
<!--NeedCopy-->
Incorrect credentials
HTTP/1.1 403 Forbidden
Cache-Control: no-cache, no-store
Citrix-Transactionid: <id>
Content-Length: <length>
Content-Security-Policy: frame-ancestors 'none'
Content-Type: application/json; charset=utf-8
Date: <date>
X-Content-Type-Options: nosniff
X-Frame-Options: deny
{"type":"https://errors-api.cloud.com/common/authorization","detail":"Authorization error"}
<!--NeedCopy-->