Prolific credentials API
The credentials API from Prolific — 2 operation(s) for credentials.
OpenAPI Specification
openapi: 3.1.0
info:
title: API Reference aiTaskBuilder credentials API
version: 1.0.0
servers:
- url: https://api.prolific.com
description: Production
tags:
- name: credentials
paths:
/api/v1/credentials/:
get:
operationId: list-credential-pools
summary: List credential pools for a workspace
description: 'Retrieve a list of credential pools belonging to a specific workspace.
Each credential pool summary includes the pool ID, total number of credentials, number of available (unredeemed) credentials, and the workspace ID.'
tags:
- credentials
parameters:
- name: workspace_id
in: query
description: The workspace ID to filter credential pools by
required: true
schema:
type: string
- name: Authorization
in: header
description: 'The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.
Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.
If your token is leaked, delete it and create a new one directly in the app.
In your requests add `Authorization` header with the value `Token <your token>`.'
required: true
schema:
type: string
responses:
'200':
description: Credential pools retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Credentials_ListCredentialPools_Response_200'
'400':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDetail'
'403':
description: Forbidden - User does not have workspace.workspace_update permission
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDetail'
'502':
description: Bad Gateway - Credentials service unavailable or internal error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDetail'
post:
operationId: create-credential-pool
summary: Create credential pool
description: 'Create a new workspace-level credential pool. Credential pools contain username/password pairs that can be assigned to participants when they start a study. This allows researchers to provide pre-provisioned credentials for third-party platforms.
The credentials are provided as a CSV string where each line contains a username and password separated by a comma (e.g., "user1,pass1\nuser2,pass2").'
tags:
- credentials
parameters:
- name: Authorization
in: header
description: 'The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.
Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.
If your token is leaked, delete it and create a new one directly in the app.
In your requests add `Authorization` header with the value `Token <your token>`.'
required: true
schema:
type: string
responses:
'201':
description: Credential pool created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Credentials_CreateCredentialPool_Response_201'
'400':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDetail'
'403':
description: Forbidden - User does not have workspace.workspace_update permission
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDetail'
'409':
description: Conflict - Duplicate credentials detected (username already exists in pool)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDetail'
'502':
description: Bad Gateway - Credentials service unavailable or internal error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDetail'
requestBody:
content:
application/json:
schema:
type: object
properties:
credentials:
type: string
description: CSV-formatted credentials (username,password per line)
workspace_id:
type: string
description: The ID of the workspace this credential pool belongs to
required:
- credentials
- workspace_id
/api/v1/credentials/{credential_pool_id}/:
patch:
operationId: update-credential-pool
summary: Update credential pool
description: 'Add new credentials to an existing credential pool. This operation is additive - new credentials are appended to the existing pool rather than replacing them. The credentials service validates that no duplicate usernames exist.
The credentials are provided as a CSV string where each line contains a username and password separated by a comma (e.g., "user4,pass4\nuser5,pass5").'
tags:
- credentials
parameters:
- name: credential_pool_id
in: path
description: Credential pool ID
required: true
schema:
type: string
- name: Authorization
in: header
description: 'The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.
Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.
If your token is leaked, delete it and create a new one directly in the app.
In your requests add `Authorization` header with the value `Token <your token>`.'
required: true
schema:
type: string
responses:
'200':
description: Credential pool updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Credentials_UpdateCredentialPool_Response_200'
'400':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDetail'
'403':
description: Forbidden - User does not have workspace.workspace_update permission
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDetail'
'404':
description: Not Found - Credential pool does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDetail'
'409':
description: Conflict - Duplicate credentials detected (username already exists in pool)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDetail'
'502':
description: Bad Gateway - Credentials service unavailable or internal error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDetail'
requestBody:
content:
application/json:
schema:
type: object
properties:
credentials:
type: string
description: CSV-formatted credentials to add (username,password per line)
required:
- credentials
components:
schemas:
Credentials_CreateCredentialPool_Response_201:
type: object
properties:
credential_pool_id:
type: string
description: The unique identifier for the created credential pool
title: Credentials_CreateCredentialPool_Response_201
Credentials_ListCredentialPools_Response_200:
type: object
properties:
credential_pools:
type: array
items:
$ref: '#/components/schemas/ApiV1CredentialsGetResponsesContentApplicationJsonSchemaCredentialPoolsItems'
title: Credentials_ListCredentialPools_Response_200
ErrorDetail:
type: object
properties:
status:
type: integer
description: Status code as in the http standards
error_code:
type: integer
description: Internal error code
title:
type: string
description: Error title
detail:
$ref: '#/components/schemas/ErrorDetailDetail'
description: Error detail
additional_information:
type: string
description: Optional extra information
traceback:
type: string
description: Optional debug information
interactive:
type: boolean
required:
- status
- error_code
- title
- detail
title: ErrorDetail
Credentials_UpdateCredentialPool_Response_200:
type: object
properties:
credential_pool_id:
type: string
description: The unique identifier for the updated credential pool
title: Credentials_UpdateCredentialPool_Response_200
ErrorDetailDetail:
oneOf:
- type: string
- type: array
items:
type: string
- $ref: '#/components/schemas/ErrorDetailDetail2'
description: Error detail
title: ErrorDetailDetail
ApiV1CredentialsGetResponsesContentApplicationJsonSchemaCredentialPoolsItems:
type: object
properties:
credential_pool_id:
type: string
description: The unique identifier for the credential pool
total_credentials:
type: integer
description: Total number of credentials in the pool
available_credentials:
type: integer
description: Number of unredeemed credentials available
title: ApiV1CredentialsGetResponsesContentApplicationJsonSchemaCredentialPoolsItems
ErrorDetailDetail2:
type: object
properties:
any_field:
type: array
items:
type: string
description: Name of the field with a validation error and as a value an array with the error descriptions
description: All fields with validation errors
title: ErrorDetailDetail2
securitySchemes:
token:
type: apiKey
in: header
name: Authorization
description: 'The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.
Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.
If your token is leaked, delete it and create a new one directly in the app.
In your requests add `Authorization` header with the value `Token <your token>`.'