Chapter 1. API Keys API

Manage the various API keys for a User account and Apps.

Note

X-FH-AUTH-USER should be in every header of every request. See API Key Management for more information.

1.1. List API keys

1.1.1. Description

List User or App API keys.

1.1.2. Endpoint

  • uri - /box/srv/1.1/ide/<domain>/api/list
  • method - POST

1.1.3. Request Body

1.1.3.1. List keys for currently logged in user

{
  "type": "user"
}

1.1.3.2. List keys belonging to given app id

{
  "type": "app",
  "appId": "<app_instance_id>"
}

1.1.4. Response Body

1.1.4.1. Success

{
  "status": "ok",
  "list": [{
    "label": "<user_friendly_id>",
    "keyType": "<key_type>",
    "key": "<public_api_key>",
    "keyReference": "<reference_id>", // for example, user/app id
    "secret": "<api_secret_key>",  // only for 'admin' group
    "revoked": "<revoked_timestamp>",
    "revokedBy": "<revoked_by_ref_id>", // for example, user id
    "revokedEmail": "<revoked_by_user_email>"
  },
  /* ... */
  ]
}

1.1.4.2. Error

{
  "status": "error",
  "message": "<error_message>"
}

1.2. Create new API keys

1.2.1. Description

Create a new User or App API key. While users can have multiple API keys associated with them, Apps can only have one active API key at any time - when an app API key is created, any pre-existing keys for that app will be automatically revoked.

1.2.2. Endpoint

  • uri - /box/srv/1.1/ide/<domain>/api/create
  • method - POST

1.2.3. Request Body

1.2.3.1. Create API Keys for the current logged in user

{
  "type": "user",
  "label": "<user_friendly_id>"
}

1.2.3.2. Create new API keys belonging to given app id

Any existing keys for this app will be automatically revoked. 

{
  "type": "app",
  "label": "<user_friendly_id>",
  "appId": "<app_instance_id>"
}

1.2.4. Success

{
  "status": "ok",
  "apiKey": {
    "label": "<user_friendly_id>",
    "keyType": "<key_type>",
    "key": "<public_api_key>",
    "keyReference": "<reference_id>", // for example, user/app id
    "secret": "<api_secret_key>",  // only for 'admin' group
    "revoked": "<revoked_timestamp>",
    "revokedBy": "<revoked_by_ref_id>", // for example, user id
    "revokedEmail": "<revoked_by_user_email>"
  }
}

1.2.5. Error

{
  "status": "error",
  "message": "<error_message>"
}

1.3. Revoke existing API keys

1.3.1. Description

Revoke existing User or App API keys.

1.3.2. Endpoint

  • uri - /box/srv/1.1/ide/<domain>/api/revoke
  • method - POST

1.3.3. Request Body

{
  "key": "<public_api_key>"
}

1.3.4. Success

{
  "status": "ok",
  "apiKey": {
    "label": "<user_friendly_id>",
    "keyType": "<key_type>",
    "key": "<public_api_key>",
    "keyReference": "<reference_id>", // for example, user/app id
    "secret": "<api_secret_key>",  // only for 'admin' group
    "revoked": "<revoked_timestamp>",
    "revokedBy": "<revoked_by_ref_id>", // for example, user id
    "revokedEmail": "<revoked_by_user_email>"
  }
}

1.3.5. Error

{
  "status": "error",
  "message": "<error_message>"
}

1.4. Delete existing API keys

1.4.1. Description

Permanently delete an existing User or App API key.

1.4.2. Endpoint

  • uri - /box/srv/1.1/ide/<domain>/api/delete
  • method - POST

1.4.3. Request Body

{
  "key": "<public_api_key>"
}

1.4.4. Success

{
  "status": "ok",
  "apiKey": {
    "label": "<user_friendly_id>",
    "keyType": "<key_type>",
    "key": "<public_api_key>",
    "keyReference": "<reference_id>", // for example, user/app id
    "secret": "<api_secret_key>",  // only for 'admin' group
    "revoked": "<revoked_timestamp>",
    "revokedBy": "<revoked_by_ref_id>", // for example, user id
    "revokedEmail": "<revoked_by_user_email>"
  }
}

1.4.5. Error

{
  "status": "error",
  "message": "<error_message>"
}

1.5. Update an existing API Key

1.5.1. Description

Update an existing App or User API Key.

1.5.2. Endpoint

  • uri - /box/srv/1.1/ide/<domain>/api/update
  • method - POST

1.5.3. Request Body

{
  "key": "<public_api_key>",
  "fields": {
    "label": "<new_user_friendly_id>"
  }
}

1.5.4. Success

{
  "status": "ok",
  "apiKey": {
    "label": "<user_friendly_id>",
    "keyType": "<key_type>",
    "key": "<public_api_key>",
    "keyReference": "<reference_id>", // for example, user/app id
    "secret": "<api_secret_key>",  // only for 'admin' group
    "revoked": "<revoked_timestamp>",
    "revokedBy": "<revoked_by_ref_id>", // for example, user id
    "revokedEmail": "<revoked_by_user_email>"
  }
}

1.5.5. Error

{
  "status": "error",
  "message": "<error_message>"
}

1.6. Validate an API Key

1.6.1. Description

Check if an API key is valid

1.6.2. Endpoint

  • uri - /box/srv/1.1/ide/<domain>/api/validate
  • method - POST

1.6.3. Request Body

{
  "type" : "<key_type>"
  "key" : "<key_value>",
}

1.6.4. Success

{
  "status" : "ok",
  "valid" : true | false
}

1.6.5. Error

{
  "status" : "error",
  "message" : "<error_message>"
}