In our system, a Project needs to be linked to a category to make navigation easier for your user. You can retrieve the existing categories to add it to your Project, or create a new one matching your needs.

Authentication

cURL request

To be able to perform actions on our API, you need to be authenticated. To do this, use the following endpoint.

curl -XPOST 'https://primary-market-api-develop.tokeny.com.tokeny.com/auth/local' \
--header 'Content-Type: application/json' \
--data-raw '{
    "identifier":"[email protected]",
    "password": "my-password"
}'

Sample response

{
    "jwt": "<jwt>",
    "user": {
        "id": 1,
        "username": "Username",
        "email": "[email protected]",
        "provider": "local",
        "confirmed": true,
        "blocked": false,
        "role": {
            "id": 34,
            "name": "Projects creators",
            "description": "Authors of projects, authenticated with the permission to manage projects, categories, issuers and disclaimers.",
            "type": "projects_manager"
        },
        "created_at": "2021-03-17T16:14:14.286Z",
        "updated_at": "2021-03-17T16:16:00.097Z"
    }
}

jwt is the jwt token that you will need to perform the next operations

Troubleshooting

{
    "statusCode": 400,
    "error": "Bad Request",
    "message": [
        {
            "messages": [
                {
                    "id": "Auth.form.error.invalid",
                    "message": "Identifier or password invalid."
                }
            ]
        }
    ],
    "data": [
        {
            "messages": [
                {
                    "id": "Auth.form.error.invalid",
                    "message": "Identifier or password invalid."
                }
            ]
        }
    ]
}

The status code can be either:

400: one of the specified credential is wrong, please check them again. In case you lost your password, please contact [email protected]
401: you are not allowed to connect to the API. If you think it is a mistake, please contact your administrator or [email protected]

Retrieve the existing categories

cURL

If categories were previously created in our system, you can retrieve them easily with the following request.

curl -XGET 'https://primary-market-api-develop.tokeny.com.tokeny.com/categories' \
--header 'Authorization: Bearer <jwt>'

jwt is the authentication token you received on the Authentication step.

Sample response

[
    {
        "id": 1,
        "name": "Equity",
        "published_at": "2020-12-02T14:57:47.510Z",
        "created_at": "2020-12-02T14:57:42.007Z",
        "updated_at": "2020-12-02T14:57:47.528Z"
    },
    {
        "id": 2,
        "name": "Bonds and Loans",
        "published_at": "2020-12-02T14:58:07.186Z",
        "created_at": "2020-12-02T14:58:04.300Z",
        "updated_at": "2020-12-02T14:58:07.203Z"
    },
    {
        "id": 3,
        "name": "Real estate",
        "published_at": "2020-12-02T14:58:17.012Z",
        "created_at": "2020-12-02T14:58:15.373Z",
        "updated_at": "2020-12-02T14:58:17.030Z"
    }
]

Troubleshooting

{
    "statusCode": 403,
    "error": "Forbidden",
    "message": "Forbidden"
}

statusCode can be:

401: your authentication token is invalid or has expired. Please go back to the Authentication step and retry
403: you are not authorized to access this resource. If you think this is an error, contact your administrator or [email protected].

Create a new category

cURL

If no existing categories match your needs, you can create a new one using the following request.

curl --location --request POST 'https://primary-market-api-develop.tokeny.com/categories' \
--header 'Authorization: Bearer <jwt>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "<category_name>"
}'

jwt is the authentication token you retrieved in the Authentication step.
category_name is the name you want to give to your new category.

Sample response

{
    "id": 34,
    "name": "Funds",
    "published_at": "2021-03-17T16:56:02.711Z",
    "created_at": "2021-03-17T16:56:02.721Z",
    "updated_at": "2021-03-17T16:56:02.721Z"
}

Troubleshooting

{
    "statusCode": 403,
    "error": "Forbidden",
    "message": "Forbidden"
}

statusCode can be:

400: you forgot to specify a mandatory field or the field doesn't match the validation rules
401: your authentication token is invalid. Go back to the Authentication step and retry.
403: you are not allowed to create categories. If you think this is an error, contact your administrator or [email protected]

Rename a category

cURL

If you need to rename a category, use the following request.

curl -XPUT 'https://primary-market-api-develop.tokeny.com/categories/<category_id>' \
--header 'Authorization: Bearer <jwt>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "<new_category_name>"
}'

jwt is the authentication token retrieved in the Authenticate step
category_id is the unique identifier of the category, retrieved though the "Retrieve the existing categories" step, or the "Create new category" step.
new_category_name is the new name that you want to give to your category.

Sample response

{
    "id": 34,
    "name": "Fund",
    "published_at": "2021-03-17T16:56:02.711Z",
    "created_at": "2021-03-17T16:56:02.721Z",
    "updated_at": "2021-03-18T09:09:46.630Z"
}

Troubleshooting

{
    "statusCode": 403,
    "error": "Forbidden",
    "message": "Forbidden"
}

statusCode can be:

400: you forgot to specify a mandatory field or the field doesn't match the validation rules
401: your authentication token is invalid. Go back to the Authentication step and retry.
403: you are not allowed to create categories. If you think this is an error, contact your administrator or [email protected]