Skip to content

API

The Switch Cloud Portal provides a RESTful API for automating tasks, integrating with external systems, and managing the portal's resources. It is intended for developers and system integrators building custom tools or workflows on top of the Portal.

The API uses standard HTTP methods, returns data in JSON format, and requires bearer token authentication. It is defined using the OpenAPI Specification and fully documented in an interactive Swagger UI, where you can explore the endpoints, view the specification, and integrate with compatible tools.

Authentication

All API requests require authentication using a bearer token.

You'll need to include the following Authorization header with each request:

Authorization: Bearer YOUR_API_TOKEN

Replace YOUR_API_TOKEN with the token you've generated from your user profile.

Example Request

curl -X GET https://cloud.switch.ch/api/v1/organisation \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Managing Tokens

API tokens are used to authenticate with the Portal when making programmatic requests. You can create and manage these tokens in your user profile.

Creating a Token

To create a new API token:

  1. Click on your name in the top-right corner of the Portal
  2. Select Profile
  3. Navigate to the API Tokens section
  4. Click on Create new token
  5. Provide the following information:
    • Organisation: Select the organisation for which this token will be scoped
    • Name: A unique and descriptive name for the token to easily identify its purpose
    • Expiry: Select the token's validity period in days (maximum validity is 90 days)
  6. Click Create

Important

The token will be displayed only once immediately after creation. Make sure to copy and store it securely, as you won't be able to retrieve it later.

Security and Best Practices

Tokens are generated securely and stored in encrypted form in the system. For optimal security and usage of the API:

  • Use a unique token for each application or integration.
  • Set appropriate expiry times based on your security requirements.
  • Implement proper error handling for API responses.
  • Store tokens securely and never expose them in client-side code.
  • Revoke unused tokens to minimize security risks.
  • Never share your tokens in public repositories or communication channels.