Reference
Migration v1 → v2
Move from authorize + token to API key + secret on the public API.
Why migrate
| v1 | v2 |
|---|---|
| Authorize → token lifecycle | API key + secret on each call |
| Token expiry management | No session token required |
| No SSE or wildcard signing | SSE + wildcard signing |
| Polling as primary status | Ping + SSE recommended |
Auth migration
| v1 | v2 replacement |
|---|---|
GET /api/v1/flow/authorize | Not needed — use x-access-secret directly |
x-access-token header | x-access-secret header |
| Token refresh logic | Remove — rotate secret via Console |
Endpoint availability
| Endpoint | v1 | v2 |
|---|---|---|
| Identification same-device | Yes | Yes |
| Identification different-device | Yes | Yes |
| Identification wildcard | Yes | Yes |
| Signing same-device | Yes | Yes |
| Signing different-device | Yes | Yes |
| Signing wildcard | No | Yes |
| Flow authorize | Yes | No |
| Flow ping | Yes | Yes |
| Flow SSE | No | Yes |
| Flow polling | Yes | Yes* |
| Flow cancel | Yes | Yes |
| Document signing | Yes | Yes |
| Document review | Yes | Yes |
| Document refresh | Yes | Yes |
* v2 polling still requires x-access-token. Prefer ping or SSE.
Header changes (summary)
| Route family | v1 | v2 |
|---|---|---|
| Identification same-device | key + secret | key + secret |
| Identification different-device | key + token | key + secret |
| Identification wildcard | key (+ token recommended) | key only |
| Signing same-device | key + secret + token | key + secret |
| Signing different-device | key + token | key + secret |
| Document * | key + token | key + secret |
Checklist
- Replace authorize + token with key + secret
- Update paths
/api/v1/→/api/v2/ - Replace long-polling with ping loop or SSE
- Add wildcard signing if needed (v2 only)
- Verify Console scopes cover v2 endpoints
- Test with
bk-test_ons.pasby.africabeforebk-live_onl.pasby.africa - Update webhook handlers if paths changed (delivery contract: Webhooks)
Legacy v1 examples remain valid for existing consumers — do not mix v1 tokens into v2 quickstarts.