> For the complete documentation index, see [llms.txt](https://speaking-test-docs.speechace.com/speechace-speaking-test/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://speaking-test-docs.speechace.com/speechace-speaking-test/speaking-test-api/keys-and-authorization.md).

# Keys and Authorization

Learn how to generate an API key and authenticate requests to the Speechace Speaking Test API.

The **Speechace Speaking Test API** uses API keys to authenticate requests. To get started, you'll need to generate an API key from your **Speechace account** and include it in the `Authorization` header of each request.

This section walks you through creating your API key, authenticating your requests, and making your first API call.

### Before you begin

You need a **Speechace** account, permission to create an API key, and an API client or development environment capable of sending HTTPS requests.

### Base URL

Once you are ready , use the following base URL for **Speaking Test API** requests:&#x20;

`https://speak.speechace.co/api/v1`

### Generate an API key

Now, lets follow these steps to create an API key from your **Speechace** account.

* You first need to sign in to your **Speechace** account.
* Now, in your workspace you will see **API Keys** below **Account .** Select the **API Keys** as shown below.

<div align="left"><figure><img src="https://2079371467-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKCjGnWORTEi39HEr4hwY%2Fuploads%2FD1IOfMK9lptxKH7TmkyL%2Fapi%20keys%20.png?alt=media&amp;token=6acbff9a-fb76-4458-be9b-c5fc55977d12" alt="" width="563"><figcaption></figcaption></figure></div>

* Once the API Keys page appears , click on **Create API Key** as shown in the image below.

<div align="left"><figure><img src="https://2079371467-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKCjGnWORTEi39HEr4hwY%2Fuploads%2F1UkfvQM4Wv3OzwcLPgGm%2Fcreate%20api%20key.png?alt=media&amp;token=73a31fd4-f082-4982-8745-281468666883" alt="" width="563"><figcaption></figcaption></figure></div>

* You will see a pop up that will ask you to create API key .You can enter a descriptive name for your API key, say for example **Speaking Test Results Integration** as shown below.

<div align="left"><figure><img src="https://2079371467-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKCjGnWORTEi39HEr4hwY%2Fuploads%2FlUMz5yZwYlloiJEDHCdP%2FScreenshot%202026-10-19%20at%204.18.02%E2%80%AFPM.png?alt=media&amp;token=86ec635b-06d4-43da-98be-73f2e4653807" alt="" width="563"><figcaption></figcaption></figure></div>

* Now , you can create the key and copy the generated value to a secure location as shown below. Ensure that you keep the key value protected and somewhere safe.

<div align="left"><figure><img src="https://2079371467-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKCjGnWORTEi39HEr4hwY%2Fuploads%2FDRK2nnrJO7A8QGvT0N0a%2FScreenshot%202026-10-19%20at%204.32.18%E2%80%AFPM.png?alt=media&amp;token=977d95a5-548a-40a8-8f08-568d27cc8676" alt="" width="563"><figcaption></figcaption></figure></div>

* Once you have copied the key value safely , click **Done** to return to the API Keys page.The generated API key will appear on the page as shown below.

<div align="left"><figure><img src="https://2079371467-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKCjGnWORTEi39HEr4hwY%2Fuploads%2Fov8XNEUsOiUxwWoTgkPT%2FScreenshot%202026-10-19%20at%204.35.40%E2%80%AFPM.png?alt=media&amp;token=86b05f07-2d41-458d-a817-61822fe11403" alt="" width="563"><figcaption></figcaption></figure></div>

You must remember your full API key may only be shown once, so make sure to save it somewhere secure.

### Authentication

The **Speechace Speaking Test API** uses **Bearer token authentication**. Include your API key in the `Authorization` header of each request:

`Authorization: Bearer YOUR_RESULTS_API_KEY`

You need to replace `YOUR_RESULTS_API_KEY` with your actual API key. You can also include `Accept: application/json` to request a JSON response.

### Make your first authenticated request

Let's try retrieving your available workspaces using the **List Workspaces** endpoint.

The block below outlines the request details, including the HTTP method, endpoint URL, and authentication requirements. You can also select your preferred programming language to view the code example and explore the expected response structure.

## List Workspaces

> Retrieve workspaces accessible to your API key.

```json
{"openapi":"3.0.3","info":{"title":"Speechace Speaking Test API","version":"0.2.5-draft"},"tags":[{"name":"Workspaces","description":"Workspace discovery"}],"servers":[{"url":"https://speak.speechace.co","description":"Speechace Speaking Test API"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}},"responses":{"Unauthorized":{"description":"The request could not be authenticated because the API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}},"schemas":{"APIError":{"type":"object","description":"Error details returned for an unsuccessful request.","required":["error"],"properties":{"error":{"type":"object","required":["message","request_id"],"properties":{"message":{"type":"string","description":"Human-readable error message."},"request_id":{"type":"string","description":"Request identifier used when contacting support."}}}}}}},"paths":{"/api/v1/workspaces":{"get":{"tags":["Workspaces"],"operationId":"listWorkspaces","summary":"List Workspaces","description":"Retrieve workspaces accessible to your API key.","responses":{"200":{"description":"Successful response in JSON containing accessible workspaces.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","description":"Workspaces accessible to your API key.","items":{"type":"object","required":["id","name","status"],"properties":{"id":{"type":"string","description":"Unique workspace identifier used in subsequent API requests."},"name":{"type":"string","description":"Display name of the workspace."},"status":{"type":"string","description":"Current workspace status."}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```

**Security note:** Always make **Speechace API** requests from your backend or server-side application. Never call these APIs directly from frontend code, as doing so may expose your API key. Keep your API key confidential and never embed it in client-side code or publicly accessible repositories.

As shown in the above example you can use the same authentication method for other **Speaking Test API** endpoints.

Now, refer to the following section explaining how to  [**List Workspaces, Assessments, and Activities**](https://speaking-test-docs.speechace.com/speechace-speaking-test/speaking-test-api/list-workspaces-assessments-and-activities.md) and retrieve the identifiers needed for subsequent Speaking Test API requests.
