@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Authentiq API
@base https://6-dot-authentiqio.appspot.com/
@version 6
@auth ApiKey secret in query
@endpoints 14
@toc key(7), login(1), scope(6)

@group key
@endpoint POST /key
@desc Register a new ID `JWT(sub, devtoken)`
@required {body: any # Authentiq ID to register}
@returns(201) Successfully registered
@errors {409: Key already registered `duplicate-key`}

@endpoint DELETE /key
@desc Revoke an Authentiq ID using email & phone.
@required {email: any # primary email associated to Key (ID), phone: any # primary phone number, international representation}
@optional {code: any # verification code sent by email}
@returns(200) Successfully deleted
@errors {401: Authentication error `auth-error`, 404: Unknown key `unknown-key`, 409: Confirm with code sent `confirm-first`}

@endpoint GET /key/{PK}
@desc Get public details of an Authentiq ID.
@required {PK: any # Public Signing Key - Authentiq ID (43 chars)}
@returns(200) Successfully retrieved
@errors {404: Unknown key `unknown-key`, 410: Key is revoked (gone). `revoked-key`}

@endpoint POST /key/{PK}
@desc update properties of an Authentiq ID.
@required {PK: any # Public Signing Key - Authentiq ID (43 chars), body: any # Authentiq ID to register}
@returns(200) Successfully updated
@errors {404: Unknown key `unknown-key`}

@endpoint HEAD /key/{PK}
@desc HEAD info on Authentiq ID
@required {PK: any # Public Signing Key - Authentiq ID (43 chars)}
@returns(200) Key exists
@errors {404: Unknown key `unknown-key`, 410: Key is revoked `revoked-key`}

@endpoint PUT /key/{PK}
@desc Update Authentiq ID by replacing the object.
@required {PK: any # Public Signing Key - Authentiq ID (43 chars), body: any # Authentiq ID to register}
@returns(200) Successfully updated
@errors {404: Unknown key `unknown-key`, 409: Already bound to another key `duplicate-hash`}

@endpoint DELETE /key/{PK}
@desc Revoke an Identity (Key) with a revocation secret
@required {PK: any # Public Signing Key - Authentiq ID (43 chars), secret: any # revokation secret}
@returns(200) Successful response
@errors {401: Key not found / wrong code `auth-error`, 404: Unknown key `unknown-key`}

@endgroup

@group login
@endpoint POST /login
@desc push sign-in request
@required {body: any # Push Token., callback: any # URI App will connect to}
@returns(200) Successful response
@errors {401: Unauthorized for this callback audience `aud-error` or JWT should be self-signed `auth-error`}

@endgroup

@group scope
@endpoint POST /scope
@desc scope verification request
@required {body: any # Claims of scope}
@optional {test: any # test only mode, using test issuer}
@returns(201) Successful response
@errors {429: Too Many Requests on same address / number `rate-limit`}

@endpoint POST /scope/{job}
@desc this is a scope confirmation
@required {job: any # Job ID (20 chars)}
@returns(202) Successfully confirmed
@errors {401: Confirmation error `auth-error`, 404: Job not found `unknown-job`, 405: JWT POSTed to scope `not-supported`}

@endpoint PUT /scope/{job}
@desc authority updates a JWT with its signature
@required {job: any # Job ID (20 chars)}
@returns(200) Successfully updated
@errors {404: Job not found `unknown-job`, 409: Job not confirmed yet `confirm-first`}

@endpoint GET /scope/{job}
@desc get the status / current content of a verification job
@required {job: any # Job ID (20 chars)}
@returns(200) Successful response (JWT)
@returns(204) Confirmed, waiting for signing
@errors {404: Job not found `unknown-job`}

@endpoint HEAD /scope/{job}
@desc HEAD to get the status of a verification job
@required {job: any # Job ID (20 chars)}
@returns(200) Confirmed and signed
@returns(204) Confirmed, waiting for signing
@errors {404: Job not found `unknown-job`}

@endpoint DELETE /scope/{job}
@desc delete a verification job
@required {job: any # Job ID (20 chars)}
@returns(200) Successfully deleted
@errors {404: Job not found `unknown-job`}

@endgroup

@end