How To

Creating Applications

Head over to https://caturra.app/dashboard/applications and create an application.

Applications Creation Screen

Oauth link

After creating the application, you should be able to copy a simple OAuth link
http://caturra.app/oauth/authorise?application_id=e2a5d0ad-93c4-4896-93de-95ea864bd18f&redirect_uri=https://caturra.app/callback/caturra

Authorisation page with default scopes

Adding default scopes

info

Note:

---

Users can change the default scopes within the authorise page.

Adding default scopes is simple; simply add &scopes= to the end of the URL using the scopes from scopes.md. This can be a string separated by a comma &scopes=user.email,user.edit OR as an array &scopes=["user.email","user.edit"]

Authorisation page with custom scopes

User Authorised

Once a user authorises your application, they will be redirected to your redirect URI with a &code= parameter. You can use this to get an access and refresh token.

Getting an access Token

info

Note:

---

By default, access tokens expire after 7 days, and refresh tokens expire after 30 days. Make sure to use the information provided by the api to determine when your tokens expire.

Getting an access token is as easy as making a post request to /code

POST /code

Body

Name	Type
code	String

Response

200

{
    "token": "Access Token",
    "token_expires_at": "2025-05-25 12:00:00",
    "refresh_token": "Refresh Token",
    "refresh_token_expires_at": "2025-06-18 12:00:00",
    "scopes": [
        "user.get",
        "user.email",
        "user.edit",
        "feed.get"
    ]
}

Refreshing a Token

Once a token expires, you can use the refresh token to gain a brand new token to use.

POST /refreshtoken

Body

Name	Type
refreshToken	String

Response

200

{
    "token": "Access Token",
    "token_expires_at": "2025-05-25 12:00:00",
    "refresh_token": "Refresh Token",
    "refresh_token_expires_at": "2025-06-18 12:00:00",
    "scopes": [
        "user.get",
        "user.email",
        "user.edit",
        "feed.get"
    ]
}