Authentication

The type of authentication you'll need depends on the application you are currently building.

• For personal scripts that involves internal workflow, we recommend to use personal API key.

• For applications that will be installed in other's workspaces and eventually become public, use oauth2.

Create a personal API key

You can generate a personal API key directly from your Cycle's settings or by triggering the createAccessToken mutation and using the token you get in your Authorisation header.

From Cycle's settings

In your Cycle workspace, navigate to your Settings -> API -> Section Personal API keys

From the mutation

mutation createToken {
  createAccessToken(label: "Notion integration") {
    id
    token
    label
  }
}

Authenticate your queries and mutations

Once you have your token, you can use it to authenticate your queries/mutations with your favorite Graphql client by placing it in your HTTP Headers.

{
  "Authorization": "Bearer <Your encoded token>"
}

You can access the list of your personal access token with the me query

query me {
  me {
    accessTokens {
      edges {
        node {
          id
          token
          label
        }
      }
    }
  }
}

And revoke them with the revokeAccessToken mutation

mutation revokeToken {
  revokeAccessToken(id: "<id>") {
    id
  }
}

When a token is revoked, you cannot access the Cycle api with it anymore. If you try, you will get CANT_SEE_PRODUCT errors or UNAUTHORIZED errors.

OAuth2

Cycle supports OAuth2 authentication, which is recommended if you're building applications to integrate with Cycle. You can create an OAuth app from the Cycle API settings or directly with the mutation:

mutation createOAuthClient {
  createOAuthClient(
    productId: "<productId>"
    name: "Dash"
    developerName: "Alan"
    developerUrl: "https://dash.app"
    callbackUrls: ["https://api.dash.app/callback"]
    isPublic: false
  ) {
    id
    clientId
    clientSecret
    developerName
    developerUrl
    callbackUrls
    isPublic
    webhookUrl
    webhookRessources
    webhookSecret
  }
}

As for any OAuth2 flow, you first need to authorise your client. You will receive a code that you can exchange for an access token.

1. Authorize

To authorize your app/user to access a product, access the following url using the correct parameters:

https://product.cycle.app/oauth/authorize

Name	Description
client_id	(required) Client ID provided when you create the OAuth2 Application
redirect_uri	(required) Redirect URI
response_type=code	(required) Expected response type
state	(optional) Prevents CSRF attacks and should always be supplied. Read more about it here

Then choose the product you want to install the app into.

2. Token

You will receive a code you can exchange for an API access token by making a post request to the following url:

POST https://api.product.cycle.app/oauth/token

Name	Description
code	(required) Authorization code from the previous step
client_id	(required) Client ID provided when you create the OAuth2 Application
client_secret	(required) Application's client secret

If the request is successful, you should receive a valid access token in the response

{
  "access_token": "<access_token>",
}

Make an API request

Once you have the token, you can make requests to the Cycle API

curl \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <Replace this with your access token>" \
  --data '{ "query": "{ me { id email } }" }' \
  https://api.product.cycle.app/graphql

Revoke the OAuth client access

To revoke the access of a third party OAuth client, you can do it from your Cycle API settings or by triggering the mutation revokeOAuthClientAccess :

mutation revokeAccess {
  revokeOAuthClientAccess(
    id: "<oauthClientId>"
    productId: "<productId>"
  ) {
    id
  }
}